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M  SCOPE 


^Thls  specification  establishes  the  performance,  design,  development,  and 
test  requirements  for  the  Program  Flow  Analyzer  (PFA)  system.  PFA  Is  a 
software  analysis  system  that  shall  Interpret  and  translate  source  language 
programs  Into  attributes  which  cl  icterize  the  design  of  the  programs.  The 
attributes  shall  then  be  processea  to  provide  an  analysis  of  the  program  based 
on  selected  PFA  requlranents.  This  specification  provides  the  user 
requirements  for  a  software  analysis  tool  to  support  the  software  development 
process.  Many  of  these  requirements  have  not  matured  to  the  point  of 
practical  application..  This  document  should  serve  as  a  living  document  to 
evolve  as  software  engineering  matures. 


2.  APPLICABLE  DOCUMENTS 


The  following  documents  form  a  part  of  this  specification  to  the  extent 
herein  specified.  In  the  event  of  a  conflict  between  the  documents  referenced 
herein  and  the  contents  of  this  specification,  the  contents  of  this  specifica¬ 
tion  shall  be  considered  as  superseding  '•equirements. 


2.1  Government  Documents 


Standards 


or 


Mil itary 
MIL-STD-490 


MIL-STD-1679 

Other  Publications 
USAEPG 


Military  Standards  Specification 
Practices,  30  October  1968 

Military  Standard  Weapon  System 
Software  Development,  1  December  1978 


Program  Flow  Analyzer  Trade-Off  Analysis 


3.  REQUIREMENTS 

3.1  System  Definition 

The  PFA  is  a  software  system  which  interprets  and  translates  source  langu¬ 
age  programs  into  data  files  which  represent  the  design  of  the  software 
program  being  analyzed. 


3.1.1  PFA  General  Description 

The  PFA  is  a  tool  used  for  the  analysis  of  a  software  program  in  order  to 
identify  software  quality,  program  structure,  and  program  maintainability. 

The  design  of  the  PFA  shall  include  the  following  functional  areas: 
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a.  Program  Structure  Analysis 

b.  Data  Flow  Analysis 

c.  Finite  State  Analysis 

d.  Error  Analysis 

e.  Program  Logic  Analysis 

f.  Software  Quality  Analysis 

g.  Software  Change  Analysis 

h.  Documentation  Development  and  Review 

3.1.2  System/Interface 

The  following  paragraphs  identify  and  describe  the  external  and  internal 
interfaces  for  the  PFA  system. 


3. 1.2.1  External  Interface 


File  management  and  some  segments  of  analysis  and  reporting  use  inter¬ 
active  commands.  Files  from  previous  runs  shall  be  archived  and  used  for  com¬ 
parison  with  files  from  new  runs.  The  user  shall  supply,  on  a  file,  the 
source  data  to  be  analyzed.  All  functions  shall  generate  reports  to  be 
printed. 


3. 1.2. 2  Internal  Interface 


All  functions  of  the  system  shall  be  independent  and  shall  interface 
through  the  data  files.  The  following  files  shall  be  used  for  functional 
interface. 


3. 1.2. 2.1  Software  Standards  File 

This  file  is  created  by  the  user  and  is  used  by  analysis  and  reporting. 
The  information  contained  in  the  software  standards  file  shall  specify 
standards  for  comparison  to  the  software  under  test  by  software  quality 
analysis. 


3. 1.2. 2. 2  Waster  File 

The  master  file  contains  all  information  on  the  structure  of  the  system 
being  analyzed.  It  is  created  by  the  encoding  function,  maintained  by  file 
management,  and  used  by  the  analysis  and  reporting  function.  The  master  file 
may  be  archived,  and  archived  master  files  may  serve  as  inputs  to  the  analysis 
and  reporting  function. 
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3. 1.2.2. 3  User  Files 


User  files  (e.g.,  Selection  File)  are  used  for  additional,  user-defined 
requirements  in  analysis  and  reporting. 


3. 1.2. 3  Host  Operating  System 

The  host  computer  shall  be  driven  by  the  support  software  operating  system 
peculiar  to  the  machine  being  used  for  PFA.  The  operating  system  with  all  its 
utility  routines  (i.e.,  file  manager,  editor,  math/ statistical  package,  tape 
input/output  (I/O)  handlers,  disk  I/O  handlers,  and  language  compiler)  shall 
be  available  in  order  that  a  request  for  services  can  be  provided  through  the 
use  of  operating  system  directives.  The  host  computer  shall  also  be  capable 
of  backing  up  the  PFA  system  files  to  tape. 


3.1.3  Government  Furnished  Property  (Target  Hardware) 

Initial  implementation  of  the  PFA  shall  be  on  the  DEC-10  and  VAX  11/780 
systems  at  Fort  Huachuca.  Delivered  software  should  be  portable  to  other  com¬ 
puters. 


3.1.4  Operational  and  Organizational  Concepts 

The  mission  of  PFA  in  relation  to  other  systems  under  development  is  to 
assess  the  quality  of  the  software  system  under  development  and  to  provide 
Information  for  testing  that  software  system. 

Anticipated  use  of  PFA  will  be  at  testing  installations  to  include  Post 
Deployment  Software  Support  Centers  (PDSSC's).  PFA  shall  also  be  useable  by 
devel opers. 


3.2  Characteristics 


3.2.1  Performance  Characteristics 

PFA  shall  read  a  representation  of  the  system  to  be  analyzed,  maintain  a 
master  data  base  file  containing  parameters  of  that  system,  perform  analysis, 
and  generate  reports  on  those  parameters. 


3.2.1.L  Program  Structure  Analysis 

Program  structure  analysis  should  consist  of  several  subfunctions: 

a.  Subroutine  Call  Structure  Chart.  A  subroutine  call  structure  chart 
shall  snow  the  subroutire  call  hierarchy,  from  the  highest  level  routine  to 
lowest  level  routine.  External  and  recursive  routines  should  also  be  iden¬ 
tified. 
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b.  HIPO  Charts.  A  HIPO  chart  shall  be  generated  for  each  module  in  the 
system  being  analyzed.  The  HIPO  chart  should  contain  the  name  of  the  module, 
a  list  of  variables  input  to  each  program  step,  a  list  of  subroutines  called 
by  each  program  step,  a  short  description  of  each  program  step,  and  a  list  of 
variables  output  from  each  program  step. 

c.  Execution  Flow  Diagram.  An  execution  flow  diagram  shall  provide  a 
graphic  representation  of  module  control  coupling  and  execution  flow  within 
each  module  of  the  software  being  analyzed.  This  graphic  representation 
should  be  in  the  form  of  a  bubble  chart.  These  graphics  should  be  machine 
generated  and  should  show  the  control  structure  of  the  software  unit  under 
test . 

d.  Path  Analysis.  Path  analysis  shall  look  at  all  paths  based  on  a 
node-branch  diagram  for  the  program  segment  and  provide  a  list  of  all  paths 
and  path  quantifiers,  i.e.,  times,  statement  counts,  and  shortest  or  longest 
path.  The  path  analysis  shall  also  identify  most  common  path  lengths  used, 
loop  identification  which  describes  the  depth  of  nesting  used,  and  path  jumps 
into  and  out  of  loops.  Path  analysis  shall  also  find  the  critical  paths 
through  the  module. 


3. 2. 1.2  Data  Flow  Analysis. 

Data  flow  analysis  should  consist  Oi'  several  subfunctions  which  perform 
the  following  analysis  and  provide  the  appropriate  reports: 

a.  Data  Flow  Diagram.  A  data  flow  diagram  shall  provide  graphic  repre¬ 
sentation  of  data  flow  between  modules  of  the  software  being  analyzed.  This 
graphic  representation  should  be  in  the  form  of  a  bubble  chart  with  variables 
itemized  on  connecting  lines  showing  directional  data  flow.  These  graphics 
should  be  machine  generated  using  a  plotter. 

b.  Module  Coupling  Analysis.  Module  coupling  is  a  metric  that  shall 
provide  information  on  the  design  of  the  target  code.  Module  coupling  is  a 
metric  for  defining  module  interdependence  for  the  sharing  of  control  and 
data.  Module  coupling  is  based  on  intermodule  control  and  data  exchange.  The 
control  and  data  coupling  between  each  module  and  every  other  module  can  be 
established  and  a  numeric  value  can  be  assigned  for  each  module-to-module 
relationship.  The  metric  can  then  be  used  to  report  the  coupling  strength  of 
the  system  under  test. 

c.  Module  Strength  Analysis.  Module  strength  (also  known  as  cohesion)  is 
another  metric  for  defining  module  interdependence  and  functional  design  that 
shall  provide  information  on  the  design  of  the  target  code.  When  the 
intramodule  strength  has  been  determined,  a  numeric  value  can  be  assigned. 

d.  Program  Stability  Analysis.  Module  coupling  and  module  strength  shall 
be  used  to  calculate  program  stability,  a  software  metric  that  describes  the 
dependency  of  each  module  and  its  relationship  with  all  other  program  modules. 
The  program  stability  metric  will  report  the  probability  for  which  a  change  in 
module  X  wi 11  have  an  effect  in  module  Y. 
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e.  Module-Level  Data  Flow  Analysis.  Module-level  data  flow  analysis 
shall  show  the  data  flow  between  each  step  of  execution  in  each  module.  This 
should  be  a  graphic  presentation  similar  to  the  data  flow  diagran  In  item  a. 

f.  Critical  Variable  Analysis.  A  critical  variable  analysis  shall  be 
used  to  find  which  variables  are  used  on  the  critical  path  of  the  module  and 
ranks  variables  as  to  their  criticality  within  the  module. 

g.  Global  Cross-Reference.  A  global  cross-reference  shall  list  all 
global  variables  used  in  the  system,  alphabetically  and  by  the  module  in  which 
they  are  used. 

3. 2. 1.3  Finite  State  Analysis 

Finite-state  modeling  should  be  used  for  locating  deadlocked  code, 
infinite  loops,  unexpected  halts,  and  areas  with  oscillating  states  (cyclic 
actions  or  processing  with  transient  intermediate  states). 


3. 2. 1.4  Error  Analysis 

Error  analysis  should  determine  (see  paragraph  3. 2. 1.2)  tne  effects  of 
errors  in  data  flowing  between  the  modules.  This  should  give  a  comprehensive 
picture  of  how  and  where  the  system  being  analyzed  may  fail. 


3. 2. 1.5  Program  Logic  Analysis 

Program  logic  analysis  should  consist  of  three  subfunctions: 

a.  Simulation/Modeling  Inputs  Generation.  The  PFA  shall  be  capable  of 
generating  a  simplified  module  structure  by  combining  units  and  paths  within 
units.  The  structure  shall  be  processable  to  produce  input  to  a  simulation 
language.  The  structure  shall  be  capable  of  tracking  input/output  operations 
for  each  module  and  the  variables  which  are  affected  by  the  decisions  in  the 
model  design. 

b.  Interface  to  Commercially  Available  Tools.  Commercially  available 
tools  should  be  evaluated  to  determine  what  analysis  reports  are  available  and 
what  their  inherent  capabilities  are  in  order  to  enhance  the  PFA  system  with 
their  attributes  or  use  their  outputs  to  complement  the  PFA  analysts  reports. 
Interface  programs  should  then  be  designed  to  extract  and  process  information 
generated  by  the  commercially  available  tools. 

c.  Symbolic  Execution  Analysis.  Dynamic  symbolic  execution  shall  simu¬ 
late  the  execution  of  each  module  and  attempt  to  execute  all  possible  paths 
through  each  module.  This  should  provide  an  exhaustive  test  of  each  module. 


3. 2. 1.6  Software  Quality  Analysis 

The  software  quality  analysis  (SQA)  function  should  consist  of  these  sub' 
functions: 


a.  Software  Profile.  The  software  profile  subfunction  shall  be  capable 
of  accepting  user-defined  software  quality  standards  for  the  purpose  of  com¬ 
paring  the  current  program  with  these  standards  (e.g.,  MIL -STD- 1679 ) . 

The  software  profile  subfunction  should  include  the  following  quantifiable 
data  provided  by  the  encoder  function: 

1.  Number  of  documentation  comments  in  the  information  prologue  of 
module. 

2.  Number  of  documentation  comments  embedded  in  Ihe  body  of  the 
module. 

3.  Number  of  lines  ir.  the  module  containing  more  than  one  executable 
statement. 

4.  Number  of  executable  statements  per  procedure. 

5.  Number  of  declaration  (nonexecutable,  non-comment)  statements  per 
module. 

6.  Number  of  control  statements  per  module. 

These  metrics  and  others,  either  alone  or  in  calculations,  shall  be  used 
to  determine  whether  or  not  a  particular  module  meets  the  standards  set  by  the 
user.  The  SQA  shall  also  provide  a  summary  of  standards  met  and  violated  by 
the  modules  in  the  system  being  analyzed. 

b.  Complexity  Analysis.  Complexity  measures  shall  be  used  to  determine 
how  simple  or  complicated  a  module  is,  either  on  an  absolute  scale  or  relative 
to  other  modules.  Complexity  analysis  should  be  imp’emented  to  determine  as 
many  different  complexity  measures  for  each  module  analyzed  as  possible. 

c.  Quality  Metrics  Analysis.  Quality  metrics  other  than  complexity 
measures  shall  be  used  to  provide  qualitative  information  about  each  module  in 
the  system  being  analyzed.  These  metrics  may  include  line  and  comment  counts 
as  used  in  the  software  profile  report,  Halstead's  measures,  or  other  metrics. 


3. 2. 1.7  Software  Chanos  Analvsis 

—  ■  -  i  ■  ■  — ■  ,  j  -  > .  —  - 

Software  change  analysis  shall  reflect  the  maturity  and  reliability  of  the 
software  under  analysis  and  should  consist  of  these  subfunctions: 

a.  Patch  Analysis.  Patch  analysis  shall  include  a  comparison  of  master 
files  of  different  program  versions  and  shall  identify  where  structure  and 
data  have  changed  and  shall  report  the  percent  of  change. 

b.  System  Configuration  Change  Analysis.  A  system  configuration  audit 
shall  be  produced  by  a  comparison  of  the  system  structure  for  all  versions  de¬ 
veloped  during  the  life  cycle  of  the  system. 
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3. 2. 1.8  Documentation  Development  and  Review 

Documentation  development  and  review  should  consist  of  these  subfunctions: 

a.  Comment  Processing.  Comment  processing  shall  read  program  source  code 
containing  specifically  formated  commencs.  These  comments  will  supply 
information  to  be  used  to  automate  documentation. 

b.  Program  Design  Language  Interface.  Program  design  language  (PDL)-to- 
PFA  interface  programs  should  extract  data  from  POL  reports  and  databases. 
These  data  will  be  compared  to  data  contained  in  a  PFA  master  file  for  the 
code  to  determine  if  the  specification  is  consistent  with  the  code  and  to 
evaluate  the  code  and  specifications  for  correctness  and  completeness. 

c.  User-Defined  Report  Generator.  A  user-defined  report  generator  should 
be  used  to  generate  custom  reports  defined  by  the  user.  The  report  generator 
shall  be  able  to  read  the  master  file  or  any  other  file  used  for  PFA  inter¬ 
face.  A  capability  of  reading  report  and  data  files  gonerated  by  other  com¬ 
mercially  available  programs  should  also  be  provided. 


3.2.2  Physical  Characteristics 


Not  applicable. 


3.2.3  Rel iabil ity 

PFA  shall  conform  to  the  following  limits  on  frequency  and  severity  of 
software  arrors  taken  from  5.10.3.1  and  5. 8. 5. 2  of  MIL-STD-1679: 


a.  The  number  of  unresolved  software  errors  (excluding  documentation 
errors)  shall  not  exceed  the  following: 


Severity 

Priority  1  and  2  (high) 
Priority  3  (medium) 

Priority  4  and  5  (low) 

b.  Intermittent  errors  shall  be 
and  receive  no  special  consideration. 


Limits 

Zero 

One  per  70K  of  machine  instruction 
words  or  fraction  thereof. 

One  per  35K  of  machine  instruction 
words  or  fraction  thereof. 

included  in  the  count  of  software  errors 


c.  The  number  of  unresolved  technical  errors  in  all  of  the  deliverable 
documentation  shall  not  exceed  the  sum  of  three,  plus  one  for  every  25K  of 
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machine  instructions  or  fraction  thereof.  For  example,  for  a  program  having 
300K  machine  instructions:  3  +  12  =  15  allowable  documentation  errors. 

d.  All  software  errors  discovered  during  the  software  quality  test  shall 
be  documented. 

e.  The  foV'owing  is  an  explanation  of  the  levels  of  software  error 
severity: 

Priority  1  -  An  error  which  prevents  the  accomplishment  of  an  oper¬ 
ational  or  mission  essential  function  in  accordance  with  official  requirements 
(e.g.,  causes  a  program  stop),  which  interferes  with  an  operator  or  mission 
essential  function,  or  which  jeopardizes  personnel  safety. 

Priority  2  -  An  error  which  adversely  affects  the  accomplishment  of 
an  operational  or  mission  essential  function  in  accordance  with  official  re- 
quirenents  co  as  to  degrade  performance  and  for  which  no  alternative  work¬ 
around  solution  exists;  or  which  interferes  with  an  operator  to  the  extent 
that  the  operator  adversely  affects  the  accomplishment  of  an  operational  or 
mission  essential  function  so  as  to  degrade  performance  and  for  which  no 
alternative  work-around  solution  exists.  (Reloading  or  restarting  the  program 
is  not  an  acceptable  work-around  solution.) 

Priority  3  -  An  error  which  adversely  affects  the  accomplishment  of 
an  operational  or  mission  essential  function  in  accordance  with  official  re¬ 
quirements  so  as  to  degrade  performance  and  for  which  there  is  a  reasonable 
alternative  work-around  solution;  or  which  interferes  with  an  operator  to  the 
extent  that  the  operator  adversely  affects  the  accomplishment  of  an  oper¬ 
ational  or  mission  essential  function  so  as  to  degrade  performance  and  for 
which  there  is  a  reasonable  alternative  work-around  solution.  (Reloading  or 
restarting  the  program  is  not  an  acceptable  work-around  solution). 

Priority  4  -  An  error  which  is  an  operator  inconvenience  or  annoyance 
and  does  not  affect  a  required  operational  or  mission  essential  function. 

Priority  5  -  All  other  errors. 


3.2.4  Maintainability 

PFA  shall  be  maintained  and  updated  on  the  basis  of  new  requirements  not 
outlined  in  this  specification.  Each  program  change  shall  include  a  test  and 
verification  phase  along  with  the  appropriate  documentation  changes. 
Quantitative  estimates  shall  be  given  for  the  following  maintenance 
considerations: 

a.  Time  and  level  of  technical  skill  needed  to  design  a  functional 
module. 

b.  The  number  and  extent  of  impacts  caused  to  existing  PFA  subprograms  by 
the  substitution  of  a  new  subprogram  for  a  pre-existent  one  and  by  the 
integration  of  an  entirely  new  subprogram  into  the  PFA. 


3.2.5  T  ransportabil ity 

The  P FA  shall  be  designed  as  a  general-purpose  software  tool,  capable  of 
being  transported  to  other  computer  systems  and  of  being  maintained  for  future 
software  evaluation  requirements  of  tactical  command  and  control  communication 
electronic  computer  systems.  The  software  shall  operate  on  comnercially 
available  hardware  and  operating  system  software  located  at  other  government 
installations. 


3.3  Design  and  Construction 


3.3.1  Workmanship 

The  PFA  shall  be  a  software  system  whose  functions  are  composed  of  com¬ 
puter  programs.  The  computer  programs  shall  be  designed  in  a  modular,  hier¬ 
archically  structured  manner.  The  design  shall  provide  the  flexibility  for 
transporting  the  program  to  other  machines  and  a  growth  potential  for  expan¬ 
sion  of  additional  software  test  capabilities  that  can  accommodate  future 
tactical  computer  systems.  The  coding  shall  be  performed  in  such  a  manner  as 
to  ensure  that  the  programs  can  be  easily  read,  understood,  tested,  and  main¬ 
tained.  The  program  source  code  listings  shall  contain  sufficient  documen¬ 
tation  to  provide  meaningful  explanations  of  the  processing  performed  by  each  • 
function.  The  design  of  the  software  shall  be  implemented  in  functional 
modules  which,  if  modified,  will  have  little  to  no  impact  on  other  modules. 

Each  program  shall  run  independently  of  the  others. 


3.3.2  Human  Performance/Human  Engineering 

PFA  shall  have  ergonomically  optimized  display  format  and  shall  allow  easy 
and  noncritical  recovery  from  operator  input  errors. 


3.4  Documentation 

The  following  paragraphs  describe  the  required  documentation  that  shall  be 
delivered  with  the  PFA. 


3.4.1  Specifications 

Appropriate  specifications  shall  be  developed  under  the  guidelines  of 
MIl-STD-1679. 


3.4.2  Supporting  Operational  Documentation 

Supporting  documentation  for  the  operation  of  PFA  shall  include  a  mainte¬ 
nance  manual  and  user's  manual,  containing  descriptions  of  the  software  system 
and  functional  details  on  control  and  operations  for  each  subsystem. 


3.5  Logistics 


3.5.1  Facilities  and  Facility  Equipment 

The  PFA  shall  operate  on  the  resources  provided  by  the  USAEPG  system 
control  facility. 


3.6  Personnel  and  Training 


3.6.1  Personnel 


PFA  shall  require  a  programmer  familiar  with  the  use  of  the  VAX  11/780  VMS 
operating  system  command  directives  and  a  working  knowledge  of  the  system 
editor  in  an  interactive  processing  mode. 


3.6.2  T  raining 

On-the-job  training  for  the  operation  of  PFA  shall  be  handled  cn  an  inter¬ 
active  basis  on  the  VAX  11/780  interactive  terminal,  following  guidelines  in 
the  PFA  user' s  manual . 


3.7  Functional  Area  Characteristics 

The  following  paragraphs  specify  the  functional  area  characteristics  re¬ 
quired  for  each  of  the  PFA  functional  areas  defined  in  paragraph  3.1. 

3.7.1  Encoding  Function 

The  modules  of  the  encoding  function  shall  perform  the  following  sub¬ 
functions: 

a.  Processing  of  input  data. 

b.  Error  processing  and  reporting. 

c.  Master  file  generation. 

d.  Listing  file  generation. 

3. 7. 1.1  Processing 

Processing  for  all  subfunctions  of  the  encoding  function  will  be  performed 
in  interactive  mode. 


fir 


3. 7. 1.2  Outputs 

The  encoding  function  will  generate  the  following  outputs: 

a.  Master  file. 

b.  Program  source  listing  file. 

3.7.2  File  Management  Function 

File  management  shall  be  performed  using  the  editor  and  file  management 
facilities  provided  by  the  commercial  operating  system. 

3. 7. 2.1  Processing 

All  editing  and  other  processing  shall  be  done  in  interactive  mode. 

3. 7. 2. 2  Outputs 

File  management  shall  generate  the  following  outputs: 

a.  Error  messages. 

b.  Updated  master  file. 

c.  Subsets  of  the  master  file. 

3.7.3  Analysis  and  Reporting  Function 

The  modules  for  analysis  and  reporting  shall  perform  the  following  sub¬ 
functions: 

a.  Program  structure  analysis. 

b.  Oata  flow  analysis 

c.  Finite  state  analysis. 

d.  Error  analysis. 

e.  Software  quality  analysis. 

f.  Program  logic  analysis 

g.  Software  change  analysis 

h.  Documentation  development  and  review 
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3. 7. 3.1  Processing 

All  of  the  above  subfunctions  shall  run  in  interactive  mode. 


3. 7. 3. 2  Outputs 

There  shall  be  at  least  one  report  generated  for  each  of  the  subfunctions 
in  3.7.3. 

4.  QUALITY  ASSURANCE  PROVISIONS 


4.1  General 

This  section  outlines  the  quality  assurance  provisions  to  be  followed  dur¬ 
ing  the  design,  development,  and  verification  of  PFA.  The  verification  of  PFA 
and  its  functional  subsystems  shall  be  consistent  with  the  phased  delivery  and 
implementation  schedules.  The  paragraphs  below  outline  the  tests  and  the  re¬ 
sponsibility  for  the  tests  of  verification  as  well  as  the  criteria  for  quality 
conformance  Inspections. 

The  verification  of  the  software  program  shall  be  accomplished  through 
system-level  testing,  unit-  and  module-level  testing,  and  software  Integration 
testing.  A  delivery  acceptance  demonstration,  based  on  the  system-level  test, 
shall  be  conducted. 

Test  documentation  relating  to  quality  assurance  (QA)  shall  be  generated 
and  maintained.  Documentation  shall  be  informal  in  nature,  consisting  of 
memos  that  document  specific  QA  monitors'  meetings,  program  design  review, 
coding  (implementation),  walkthroughs,  etc.  This  documentation  shall  be  made 
available  on  request.  QA  information  saved/stored  shall  Include,  as  a 
minimum,  the  following: 

a.  Software  problems — system  Integration 

b.  Software  problems— module  integration 

c.  Operations,  user  manual  discrepancies 

d.  Project  status/ accountabil ity  data 

The  user  manual  for  this  software  shall  also  be  subject  to  review  and  ap¬ 
proval  . 

Acceptance  of  the  software  specification  delivery  shall  be  based  upon  the 
satisfactory  demonstration  of  its  performance  and  reliability.  The  delivery 
acceptance  demonstration  of  the  system  progran  shall  consist  of  system-level 
testing  designed  to  verify  that  the  overall  requirements  of  the  system  and  its 


Interface  with  Its  subsystems  are  met.  Records  on  all  software  problems  en¬ 
countered  during  testings  and  on  data  relating  to  the  resolution  and  repair  of 
these  problems  shall  be  maintained.  The  system  delivery  shall  not  be  con¬ 
sidered  accepted  until  all  reported  discrepancies  have  been  corrected. 


4.1.1  Responsibility  for  Tests 

Unless  otherwise  specified  in  the  contract  or  task  order,  the  supplier 
shall  be  responsible  for  the  performance  of  all  inspection  requirements  as 
specified  herein.  Except  as  otherwise  specified,  the  supplier  may  utilize  his 
own  facilities  or  any  commercial  computer  facility  acceptable  to  the  govern¬ 
ment.  The  government  reserves  the  right  to  perform  any  of  the  inspections  set 
forth  in  the  specification  where  such  inspections  are  deemed  necessary  to  as¬ 
sure  that  supplies  and  services  conform  to  prescribed  requirements. 


4.1.2  Special  Tests  and  Examinations 

The  following  tests  shall  be  performed  by  the  contractor  in  the  verifica¬ 
tion  of  PFA. 


4. 1.2.1  Unit-  and  Module-level  Testing 

Unit-  and  module-level  testing  shall  be  performed  to  ensure  the  cor¬ 
rectness  of  each  program  module  prior  to  software  integration  testing.  Each 
unit  of  each  module  shall  be  tested  Independently  to  verify  its  compliance 
with  the  appropriate  module-level  requirements.  This  testing  shall  be  ac¬ 
complished  on  an  informal  basis,  using  informal  test  documentation.  All  test 
failures  shall  be  documented  upon  occurrence.  Units  and  modules  shall  be  re¬ 
tested  whenever  a  software  correction  is  implemented.  Complete  path  testing 
shall  be  made  at  the  unit  level.  Unit-and  module-level  testing  may  be  done 
concurrently  with  software  integration  testing. 


4. 1.2. 2  Software  Integration  Testing 

Software  Integration  testing  shall  be  performed  to  verify  the  performance 
of  larger  program  segments  and  module  interfaces.  This  testing  shall  be  ac¬ 
complished  during  the  phased  integration  of  the  program  modules.  As  each  mod¬ 
ule  is  integrated  into  the  system  program,  that  module's  interfaces  with  the 
other  Integrated  modules  shall  be  tested.  This  testing  shall  be  accomplished 
Informally  using  Internal  software  test  plans  and  procedures.  When  a  test 
failure  occurs.  It  shall  be  documented,  and  integration  testing  shall  be  sus¬ 
pended  until  the  problem  is  successfully  corrected. 


4. 1.2. 3  System-level  Testing 


The  system  program  shall  be  tested  on  the  system  level  to  verify  that  the 


overall  requirements  of  the  system  and  its  subsystems  are  met.  Records  snail 
be  maintained  cn  all  software  problems  encountered  during  testing  and  on  the 
resolution  of  these  problems. 
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4.2  Quality  Conformance  Inspections 

This  paragraph  presents  quality  conformance  inspection  criteria  to  be  ap¬ 
plied  during  the  design,  development,  and  verification  of  PFA.  The  quality 
conformance  inspections  shall  include  reviews  of  the  following  categories  of 
documentation:  design  documents  (specifications),  supporting  documentation 
(operational  guide  or  user  manual),  program  listings  (module  source  code),  and 
status  accountability  reports.  A  System  Design  Review  (SDR)  shall  be  held  to 
discuss  the  software  requirements  as  presented  in  this  specification.  The  de¬ 
livery  of  both  the  performance  and  design  specifications  shall  be  followed  by 
design  reviews.  An  SDR  shall  also  be  held  to  discuss  the  functional  design  as 
presented  in  the  program  performance  specification.  A  Critical  Design  Review 
(CDR)  shall  be  held  to  discuss  the  detailed  implementation-level  design  as 
presented  in  the  program  design  specification.  The  design  review  shall  be 
scheduled  approximately  three  weeks  after  delivery  of  each  specification.  Ad¬ 
ditional  interim  design  reviews  may  also  be  scheduled. 

A  Verification  Cross-Reference  Index  (VCRI)  (Table  I)  shall  be  used  to 
provide  for  the  direct  identification  of  each  Section  3  requirement  and  the 
associated  method  for  verifying  that  the  requirements  has  been  satisfied.  An 
N/A  in  the  VCRI  paragraph  list  indicates  that  there  is  no  verifiable  re¬ 
quirement  in  the  Section  3  paragraph. 

The  quality  conformance  Inspections  jf  the  program  listings  shall  include 
several  separate  procedures.  First,  a  review  shall  be  made  of  the  module 
listings  and  the  program  design  specifications  to  verify  that  a  module  listing 
exists  for  each  module  identified  in  the  program  design  specifications  and  to 
verify  that  each  module  for  which  a  module  listings  exists  was  identified  in 
the  program  design  specification.  The  listings  for  each  separately  assembled 
or  compiled  module  shall  then  be  reviewed,  using  the  following  criteria: 

a.  The  module  shall  contain  the  complete  processing  for  that  function  or 
subfunction,  to  permit  modification  of  that  function/module  without  requiring 
modification  of  other  modules. 

b.  The  module  listing  shall  contain  a  prologue  comment  section  which 
identifies  the  module,  the  system,  the  module  inputs  and  outputs,  error  con¬ 
ditions  and  error  processing,  and  a  brief  description  of  the  module's  func¬ 
tion. 


c.  The  module  listing  shall  contain  comments  to  describe  the  inputs, 
processing,  and  outputs  for  each  routine  and  subroutine. 

d.  The  program  flow  within  the  module  listing  shall  be  consistent  with 
the  program  flow  defined  in  the  program  design  specification. 

Quality  conformance  Inspection  shall  also  include  the  review  of  status  re¬ 
ports  and  monitoring  of  the  status  and  accountability  information  throughout 
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TABLE  I.  VERIFICAlfON  CROSS-REFERENCE  INDEX 
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Method:  Category: 

^Inspection  S=Software  Integration  Testing 

D=Demonstration  R=Design  Review 

'  T=Test  and  Review  of  Test  Data 
N/A=Not  Applicable 


TABLE  I.  VERIFICATION  CROSS-REFERENCE  INDEX  (Continued) 


Method:  Category: 

^Inspection  S=Software  Integration  Testing 

D=Demonstration  R=De$1gn  Review 

I/teStaKdpp?f?^e°f  TCSt  Data 


TABLE  I.  VERIFICATION  CRU5S-REFERENCE  INDEX  (Continued) 
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i-inspecLion  S-Software  Integration  Testing 

D=Demon strati  on  R=Design  Review 

T=Test  and  Review  of  Test  Data 
'  N/A=Not  Applicc^le 
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T=Test  and  Review  of  Test  Data 
N/A=Not  Applicable 


each  phase  of  the  software  development  effort.  As  a  minimum,  the  following 
status  information  shall  be  provided  for  each  module  and  module  subroutine  de¬ 
fined  In  the  program  design  specifications: 

a.  Coding  effort  started. 

b.  Coding  effort  completed. 

c.  Module- level  testing  started. 

d.  Module-level  testing  completed. 

e.  System-level  testing  started. 

f.  System-level  testing  completed. 

A  record  shall  also  be  maintained  of  all  software  problems  encountered 
during  testing  and  of  how  each  was  resolved.  For  each  software  specification 
delivery,  a  list  of  the  functional  capabilities  provided  in  that  specification 
delivery  shall  be  established  and  the  testing/verification  status  of  each 
shal 1  be  maintained. 
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5.  PREPARATION  FOR  DELIVERY 


The  preparation  for  the  PFA  delivery  shall  include  the  following  steps: 

a.  Generation  of  source  code  listings  of  all  programs  being  delivered. 

b.  Generation  of  a  machine  readable  software  source. 

c.  Updated  operational  guides,  if  required.  All  software  deliveries 
shall  be  in  accordance  with  the  phased  development  and  implementation  schedule 
agreed  upon. 
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SECTION  1.  GENERAL 


1.1  Purpose  of  the  Users  Manual .  The  objective  of  the  Users  Manual  for  the 
Program  Flow  Analyzer  { PFA)  system,  TECOM  Project  Number  7-C0-RD0-EP1-0G4,  is  to 
provide  non-ADP  personnel  with  the  information  necessary  to  use  the  PFA  system 
effectively. 

This  manual  reflects  the  current  implementation  of  the  PFA  system  on  the  VAX 
computer.  The  capabilities  described  in  this  document  represent  a  subset  of  the 
planned  system  as  defined  In  the  PFA  A-level  specification. 

1.2  Project  References.  PFA  Is  a  software  analysis  system.  It  is  made  up  of 
various  programs  which  identify  software  quality,  structure,  modification,  and 
features  which  aid  or  interfere  with  program  maintainability  and  reliability. 

PFA  is  sponsored  by  the  US  Army  Electronic  Proving  Ground  (USAEPG)  at  Fort 
Huachuca,  Arizona. 

The  following  documents  are  applicable: 

a.  USAEPG,  Methodology  Investigation  Proposal — Program  Flow  Analyzer,  March 
1979. 

b.  USAEPG,  Program  Flow  Analyzer  A-level  Specification,  4  April  1980. 

c.  USAEPG,  Program  Flow  Analyzer  Detailed  Work  Plan,  30  October  1982. 

d.  Leslie  Claudio,  Methodology  Investigation  Final  Report— Program  Flow  An¬ 
alyzer,  30  October  1982. 

e.  USAEPG,  PLRS  DT-II  Final  Report.  December  1981. 

f.  Department  of  Defense,  D0D-STD-7935.1-S,  Automated  Data  Systems  Doc¬ 
umentation  Standards,  13  September  1977. 

g.  Department  of  Defense  (Navy),  MIL-STD-1679,  Weapon  System  Software  De¬ 
velopment,  1  December  1978.  “~J"~ 


1.3  Terms  and  Abbreviations.  Terms,  abbreviations,  acronyms,  and  definitions 
are  given  in  appendix  A. 

1.4  Security  and  Privacy.  The  PFA  system  is  unclassified  and  is  currently  set 
up  to  identify  all  output  as  unclassified.  To  process  classified  information 
the  program  must  be  modified. 
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SECTION  2.  SYSTEM  SUMMARY 


2.1  System  Application.  PFA  is  a  software  tool  for  automating  software  anal- 
yses  which  are  normally  performed  manually.  These  analyses  are  time  consuming 
and  are  often  omitted. 

PFA  provides  system  structure,  module  structure,  software  quality  assess¬ 
ment,  and  system-level  and  module-level  comparison  of  versions  of  software.  PFA 
can  also  be  used  to  generate  system  documentation. 

Document  review  of  code  and  design-level  specifications,  software  quality 
metrics,  and  comparison  of  different  versions  of  software  are  normally  performed 
manual iy.  PFA  generates  reports  that  are  comparable  to  design  specifications; 
this  reduces  the  effort  needed  to  trace  from  code  to  design  specifications.  PFA 
computes  and  compares  software  quality  metrics  to  user-selected  software  quality 
standards,  thereby  automating  the  software  quality  assessment.  PFA  compares  two 
versions  of  software,  in  an  overall  comparison  and  then  a  comparison  of  selected 
modules,  and  generates  reports  which  clearly  locate  changes. 

2.2  System  Operation.  The  PFA  system  can  be  used  by  the  developer,  the 
independent  verification  and  validation  (V&V)  contractor,  the  independent  de¬ 
velopment  test  and  evaluation  (IDT&E)  activity,  the  independent  evaluation 
activity,  and  the  post-deployment  software  support  (PDSS)  activity.  Figure  2-1 
shows  the  relationship  of  the  various  users  of  PFA  within  the  acquisition  life 
cycle.  The  shaded  areas  show  when  PFA  can  be  used  and  who  might  use  it. 

PFA  reduces  the  effort  required  to  document  a  system.  Using  COMPRO  or  a 
full  capability  encoder  with  STAMP  provides  the  developer  with  a  procedure  call 
structure  chart  and  HIPD  charts  for  each  procedure.  These  can  be  used  to  create 
or  update  program  documentation  CPCIs. 

PFA  reduces  the  effort  for  documentation  reviews.  The  system-specific  en¬ 
coder  and  the  STAMP  program  provide  the  Independent  V&V  and  development  tester 
with  procedure  call  structure  charts  and  HIPO  charts  which  are  comparable  with 
the  developer's  program  documentation  CPCIs.  Lists  of  procedures  called  which 
are  external  to  the  developer's  software,  a  list  of  the  highest  level  procedures 
to  compare  against  the  functions  described  in  function  specifications,  and  an 
alphabetical  directory  of  all  procedures  supplied  by  the  developer  are  also 
provided . 

PFA  reduces  the  effort  required  to  check  software  against  standards  and 
software  quality  metrics.  The  system-specific  encoder  and  the  SOFTPRO  program 
provide  the  developer  and  tester  with  a  list  of  procedures,  pointing  out  the  de¬ 
viations  from  software  standards  and  acceptable  software  quality  measures  for 
each  procedure. 

PFA  reduces  the  effort  required  to  monitor  changes  between  old  and  new 
versions  of  software.  The  system-specific  encoder  and  the  SYSTRUCT  and  PATCHANA 
programs  provide  the  developer,  configuration  controller,  and  testers  with  an 
audit  of  changes  between  two  versions  of  the  same  software  from  the  system  level 
and  the  procedure  level.  Figure  2-2  shows  an  assignment  of  configuration 
control  responsibilities  during  various  periods  in  the  acquisition  cycle. 

Figure  2-3  shows  the  relationship  of  the  various  user  activities  to  the 
individual  programs  of  the  PFA  system. 


The  shaded  areas  indicate  PFA  use 
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Figure  2-3.  PFA  End  User  Activities 


2.3  System  Configuration.  PFA  is  currently  implemented  on  a  DEC  VAX/VMS  sys- 
tem,  model  11/7&0,  and  requires  a  dis*  and  a  9-track  tape  drive. 

2.4  System  Organization.  The  flow  of  data  through  the  system  is  shown  in 
figure  2-4 .  A  general  description  of  the  organization  of  the  PFA  system  is 
provided  below. 

2.4.1  Encoder  (AUTOxxxx).  The  encoder  is  a  front-end  program  to  the  PFA  sys- 
tem,  customized  for  each  application  to  accommodate  the  specific  machine/lan¬ 
guage  combination  of  the  software  system  being  analyzed,  which  translates  com¬ 
puter/software/language  specific  programs  into  a  representation  which  is  stored 
in  a  data  base  called  the  master  file.  This  master  file  is  then  read  by  other 
PFA  programs  that  generate  reports. 

2.4.2  Comment  Processor  (COMPRO).  COMPRO  extracts  and  processes  comments  for 
creating  documentation.  COMPRO  reads  program  source  code  files  which  contain 
comments  in  ,  specific  format  and  creates  a  master  file  which  can  be  processed 
by  other  PFA  prograns  to  generate  reports  used  for  program  documentation.  PFA 
programs  are  commented  in  this  manner  to  provide  automated  HIPO  and  structure 
charts  for  the  PFA  system.  A  source  listing  of  the  input  is  also  provided. 

2.4.3  Structure,  Timing,  Analysis,  Modeling  Program  (STAMP).  STAMP  performs 
program  structure  analysis.  The  STAMP  program  reads  the  master  file  and 
generates  reports  on  the  overall  system  under  analysis  to  aid  in  modeling  that 
system  and  to  orovide  information  about  the  structure  of  that  system. 

GT  2.4.4  Software  Profile  Program  (SOFTPRO).  SOFTPRO  performs  software  quality 
analysis.  SOFTPRO  reads  the  master  file  and  a  software  standards  file  and 
generates  two  reports  on  software  standards  violations. 

2.4.5  System  Structure  Comparator  (SYSTRUCT) .  SYSTRUCT  performs  analysis  of 
system  configuration  chanqes.  SYSlft'JCT  reads  two  master  files  representing  dif¬ 
ferent  versions  of  the  software  system  under  analysis.  SYSTRUCT  generates  a  re¬ 
port  on  system-level  changes  in  the  analyzed  system. 

2.4.6  Patch  Analysis  Program  (^CHANA).  PATCHANA  performs  software  patch 
(source  code  change!  analysis.  PATCHANA  reads  two  master  files  or  subsets  of 
master  files  (work  files)  representing  two  versions  of  the  software  being 
analyzed.  Selection  can  be  made  interactively  or  via  the  selection  file,  wl.ich 
contains  a  list  of  modules  to  be  compared.  The  report  lists  the  path  segment 
structure  for  both  versions  side  by  side  and  indicates  (with  codes  and  arrows) 
the  location  of  differences  and  what  was  changed  for  each  version. 

2.5  Performance.  PFA  supports  various  software  evaluation  activities  by  re- 
ducing  the  effort  required  to  perform  those  activities  manually  or  by  making 
performance  of  those  activities  feasible,  given  constraints  on  time  and  effort. 
PFA  reduces  effort  by  presenting  its  output  in  a  format  which  is  comparable  to 
the  CPCI  for  the  program  under  analysis. 

To  process  a  master  file  containing  about  200  modules,  the  STAMP  program 
—  takes  one  hour,  SOFTPRO  takes  about  15  minutes,  and  SYSTRUCT  takes  30  minutes. 
PATCHANA  takes  about  two  minutes  per  module  to  be  compared  if  full  master  files 
are  used,  less  if  work  files  are  used. 
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2.6  Data  Bases.  PFA  uses  two  data  base  files,  the  master  file  and  the 
standards  file.  The  master  file  contains  summary  information  on  the  program  to 
be  analyzed.  It  is  used  by  STAMP,  SOFTPRO,  SYSTRIJCT,  and  PATCHANA  to  analyze 
and  report  on  program  structure,  maintainability,  and  software  quality. 

The  standards  file  contains  information  on  software  standards.  It  is  used 
by  SOFTPRO  to  calculate  and  report  standards  violations  by  the  program  being 
analyzed  and  by  SYSTRUCT  to  identify  software  quality  metrics  being  compared. 

2.7  General  Description  of  Inputs,  Processing,  Outputs.  Following  is  a  general 
description  of  PFA  inputs,  data  flow,  and  resultant  outputs. 

2.7.1  Inputs.  Table  2-1  lists  inputs  for  the  PFA  programs. 

2. 7.1.1  Source  Files.  The  only  PFA  programs  to  use  software  source  files  are 
COMRRO  and  AlJTOxxxx  (system-specific  encoders). 

2. 7. 1.2  Standards  File.  The  standards  file  is  used  by  SOFTPRO  and  SYSTRUCT  to 
calculate  and  report  software  standards  violations.  The  standards  file  de¬ 
scribes  various  software  standards,  including  such  information  as  description, 
range  to  be  within  standard,  expression  for  calculation.  Military  Standard  Ref¬ 
erence,  and  type  of  standard  (code  or  documentation).  The  standards  file  is 
created  in  two  parts.  The  first  part  is  created  when  the  encoder  is  written. 

It  contains  the  descriptions  of  the  basic  standards,  those  standards  whose 
values  are  calculated  by  the  encoder  and  output  in  the  master  file.  The  second 
part  of  the  standards  file  is  created  by  the  user  any  time  before  PFA  run  time. 
It  contains  the  user-defined  standards,  those  standards  which  are  calculated  in 
terms  of  the  basic  standards  or  other  user-defined  standards.  These  two  parts 
exist  in  the  same  file  and  may  be  intermixed.  The  name  of  the  standards  file  to 
be  used  is  specified  by  the  user,  but  by  convention  has  the  extension  STD. 

2. 7.1. 3  Master  File.  The  master  file,  or  a  subset  of  it,  is  used  by  STAMP, 
SOFTPRO,  SYSTRUCT,  and  PATCHANA  to  analyze  and  report  on  program  structure, 
maintainability,  software  quality  and  source  cede  changes.  The  master  file 
contains  summary  information  on  the  program  being  analyzed.  This  information 
includes  the  module  names,  prologues,  flow  of  control,  subroutine  calls, 
variable  usaqe,  comments,  entry  points,  and  values  of  varying  software 
qualities.  The  master  file  is  output  by  an  encoder  or  COMPRO.  The  name  of  the 
master  file  to  be  used  is  specified  by  the  user,  but  by  convention  has  the 
extension  MST. 

2. 7. 1.4  Selection  File.  The  selection  file  contains  the  names  of  the  modules 
in  the  master  file  to  be  processed  by  PATCHANA.  It  is  optional,  as  the  module 
names  may  also  be  specified  at  run  time.  The  selection  file  may  have  been 
prepared  manually  by  the  user,  or  it  may  have  been  output  by  SYSTRUCT.  The 
selection  file  output  by  SYSTRUCT  contains  the  names  of  the  modules  determined 
to  have  probable  code-level  changes. 

2. 7. 1.5  Terminal  Inputs.  The  terminal  inputs  are  those  inputs  which  the  user 
may  provide  at  the  console.  Terminal  inputs  are  required  at  the  beginning  of 
STAMP,  SOFTPRO,  PATCHANA,  SYSTRUCT,  and  COMPRO  runs.  The  program  prompts  for 
user  responses  such  as  input  file  names,  output  file  names,  and  specification  of 
desired  reports  and  program  options. 
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TABLE  2-1.  INPUTS  AND  OUTPUTS  OF  PFA  PROGRAMS 


PROGRAM 

COMPRO 

STAMP 

SO  FT  PRO 

SYSTRUCT 


INPUTS 

PFA  Source  Listings 


Master  File 


Master  File 
Standards  File 


Master  File 
Standards  File 


OUTPUTS 


Master  File 
Encoder  Listing 

External  Procedures  Report 
Function  List 
Structure  Charts 
Module  List 
HIPO  Charts 

Software  Standards 
Violations  Details 
Report 

Software  Standards 
Violations  Summary 
Report 

Report 

Selection  File 


PATCH  ANA 


Two  Master  Files  or  Subsets 
Selection  File  (Optional) 


Report 


2,7.2  Processing.  The  flow  of  data  between  PFA  programs  is  shown  in  figure 
2-4.  In  addition,  the  terminal  inputs  to  STAMP,  SOFTPRO,  SYSTRUCT,  and  PATCHANA 
are  used  to  select  the  analysis  options  and  the  reports  to  be  output. 

2. 7. 2.1  Encoder  (AUTOxxxx).  The  encoder  is  a  front-end  program  to  the  PFA  sys- 
tem  which  translates  computer/software/language-specif ic  programs  into  a  rep¬ 
resentation  which  is  stored  in  a  data  base  called  the  master  file.  This  master 
file  is  then  read  by  other  PFA  programs  which  generate  reports.  The  encoder  is 
customized  for  each  application  to  accommodate  the  specific  machine/language 
combination  of  the  software  system  being  analyzed. 

2. 7. 2. 2  Comment  Processor  (COMPRO).  COMPRO  extracts  source  code  comments  for 
creating  documentation.  COMPRO  reads  program  source  code  files  which  contain 
comments  in  a  specific  format.  The  information  contained  in  these  comments  is 
used  to  create  a  master  file  which  can  be  processed  by  other  PFA  programs  to 
generate  reports  used  for  program  documentation.  PFA  programs  are  commented  in 
this  manner  to  provide  automated  HIPO  and  structure  charts  for  the  PFA  system. 

2. 7. 2. 3  Structure,  Timing,  Analysis,  Modeling  Program  (STAMP).  STAMP  orovides 
the  program  structure  analysis  function.  The  STAMP  program  reads  the  master 
file  and  generates  reports  on  the  overall  system  under  analysis  to  aid  in 
modeling  that  system  and  to  provide  information  about  its  structure.  ST ATIP 
processes  the  master  file  (PFA  data  base)  to  produce  the  structure  charts  from 
the  subroutine  calls  information  in  the  master  file.  STAMP  also  extracts  the 
module  names  to  provide  module  and  function  lists.  Additionally,  the  extracted 
function  and  module  names  are  examined  to  determine  which  routines  are  not 
defined  locally,  and  outputs  these  in  an  external  procedures  report. 

STAMP  develops  a  HIPO  cnart  based  upon  module  information.  The  module  name, 
description,  prologue  comments,  and  path  segment  information  (inputs,  outputs, 
quantifiers,  node-path  labels/branches,  and  inline  comments)  are  reported  from 
the  master  file.  Information  on  modules  called  and  calling  modules  is  derived 
from  subroutine  calls  information.  This  process  of  creating  the  HIPO  chart  is 
then  repeated  for  each  module  defined  in  the  master  file. 

2.7. 2. 4  Software  Profile  Program  (SOFTPRO).  SOFTPRO  provides  the  software 
quality  analysis  function.  It  requires  as  input  both  a  master  file  and  software 
standards  file. 

SOFTPRO  takes  the  formulas  from  the  standards  file  and  data  from  the 
software  quality  records  of  the  master,  file  and  computes  the  values  of  the 
software  quality  parameters.  It  then  takes  the  ranges  from  the  standards  file 
and  determines  which  parameters  are  within  allowable  ranges.  The  results  of  the 
computations  are  passed  to  the  output  section  to  generate  the  exception,  summary 
and  other  reports. 

2. 7. 2. 5  System  Structures  Comparator  (SYSTRUCT).  SYSTRUCT  provides  analysis  of 
system  configuration  changes.  SYSTRUCT  reads  two  master  files  representing 
different  versions  of  the  software  system  under  analysis  and  generates  a  report 
on  system-level  changes.  These  changes,  determined  at  the  module  level,  are 
derived  by  examining  differences  in  subroutine  calls,  number  of  paths,  and  the 
software  quality  metrics  between  the  two  versions.  This  information  is  then 
formatted  into  a  report  for  each  module  which  displays  both  the  old  and  new 
information  and  an  indication  of  which  items  changed. 


2.7. 2. 6  Patch  Analysis  Program  (PATCHANA).  PATCHANA  provides  a  software  patch 
(source  code  change)  analysis  function.  PATCHANA  reads  two  master  files  or  sub¬ 
sets  of  master  files  representing  two  versions  of  the  software  being  analyzed. 

A  selection  file  which  contains  a  list  of  modules  to  be  compared  is  also  read. 

The  master  files  are  examined  to  locate  information  on  the  modules  listed  in 
the  selection  file.  Path  segment  information,  for  the  old  and  new  modules,  is 
processed  to  identify  differences  in  structure,  subroutine  calls,  variable 
usage,  and  the  three  quantifiers.  This  information  is  presented  in  a  report 
which  lists  both  versions  of  the  module  and  flags  the  differences. 

2.7.3  Outputs.  Table  2-1  lists  PFA  program  outputs. 

2. 7. 3.1  AUTOxxxx  and  COMPRO.  AUTOxxxx  and  COMPRO  output  master  files  and  re- 
fonmatted  source  listings.  COMPRO1 s  master  file  is  based  on  specially  formatted 
comments  in  the  input  source  listings. 

2. 7. 3. 2  STAMP.  STAMP  provides  five  reports,  as  follows: 

a.  The  external  procedures  report  lists  each  module  which  calls  subroutines 
outside  the  set  of  modules  being  analyzed  and  the  name  of  the  sub¬ 
routines  called. 

b.  The  structure  chart  shows  the  module  call  hierarchy  of  the  system  and 
flags  external  and  recursive  subroutines. 

c.  The  function  list  provides  a  list  of  all  task-level  modules  in  the  sys¬ 
tem,  with  the  name  of  the  module,  a  brief  description,  and  version 
information. 

d.  The  module  list  contains  a  directory  of  the  modules  being  analyzed,  ar¬ 
ranged  in  alphabetical  order.  It  also  contains  an  indicator  to  signal 
whether  the  module  is  cask  level,  subroutine  level  or  an  unused  entry 
point;  the  top  and  bottom  hierarchical  level  on  which  the  module  is 
called;  a  brief  module  description;  the  version  information;  and  the 
page  number  of  the  source  listing  where  the  module  is  located. 

e.  The  HIPO  chart  lists  the  name  of  the  module,  a  brief  description,  the 
version  information,  and  the  page  number  of  the  source  description.  The 
HIPO  chart  also  includes  the  path  segment  structure  of  the  module.  Each 
path  segment  contains  the  names  of  modules  called,  comments  about  the 
path,  three  quantifiers  (discussed  below)  and  the  sequence  number  range 
of  the  source  statements  which  make  up  the  path  segment.  The  path  seg¬ 
ment  information  includes  inputs  and  outputs  for  the  segment. 

The  quantifiers  are  user-selected  values  (determined  by  the  particular  en¬ 
coder  used)  extracted  f ron  the  software  being  analyzed.  Examples  are  execution 
module  timing,  source  statement  counts,  and  machine  instruction  counts  and  are 
determined  by  encoder  design.  Those  itans  which  are  not  available  do  not 
prohibit  processing.  The  STAMP  program  will  report  whatever  information  is 
available. 
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2. 7. 3. 3  SOfTPRO.  SOFTPRO  provides  two  reports,  as  follows: 


a.  The  software  profile  reports  for  each  module  list  the  violations  of 
software  standards  as  defined  by  the  user  in  the  software  standards 
file.  The  violations  state  the  standard,  the  value  for  the  software 
being  analyzed,  the  permitted  range  of  values,  and  the  reference  to  the 
regulation  from  which  the  standard  is  derived. 

b.  The  profile  summary  contains  the  list  of  standards,  the  number  and  per¬ 
cent  of  modules  meeting  each  standard,  the  number  and  percent  of  modules 
violating  each  standard,  and  the  reference  to  the  regulations  containing 
each  standard.  Additionally,  the  quality  values  are  summarized  for  all 
the  modules  and  listed  individually  for  each  module. 

2. 7.3. 4  SYSTRUCT.  The  SYSTRUCT  report  lists  changes  in  variables  used  by  each 
module,  changes  in  software  quality  parameters  (the  ones  reported  by  SOFTPRO), 
and  modules  which  have  been  added  to  or  deleted  from  the  current  version  of  the 
software  being  analyzed.  The  changes  are  of  two  types:  those  affecting  exe¬ 
cutable  code  and  those  affecting  code  documentation.  When  changes  affect  exe¬ 
cutable  code,  a  list  of  changed  modules  is  generated  for  use  by  the  patch  an¬ 
alysis  program. 

2. 7. 3. 5  PATCHANA.  The  PATCHANA  report  lists  the  path  segment  structure  for 
both  versions  side  by  side  and  indicates  (with  codes  and  arrows)  the  location  of 
differences  and  what  was  changed  for  each  version.  When  structural  differences 
occur,  the  differences  are  flagged  from  their  start  either  through  the  remainder 
of  the  module  or  to  the  point  where  the  structures  of  the  two  versions  are  con¬ 
gruent.  PATCHANA  finds  differences  in  structure,  subroutine  calls,  variable  us¬ 
age,  and  the  three  quantifiers. 


SECTION  3.  STAFF  FUNCTIONS  RELATED  TO  TECHNICAL  OPERATIONS 


3.1  Initiation  Procedures.  The  first  step  for  using  PFA  for  software  analysis 
Is  to  obtain  the  encoder,  with  documentation,  for  the  particular  programming 
language  and  computer  system  for  which  the  software  being  analyzed  Is  written. 

The  second  step  is  to  obtain  the  source  code  or  compile  listing  for  the 
software  under  analysis  on  machine-readable  form  (tape  or  disk). 

Next  a  file  containing  software  standards  to  be  applied  to  the  software 
under  analysis  must  be  prepared,  and  the  encoder  must  be  run  to  create  the 
master  file. 

The  system  manuals  for  the  particular  computer  system  where  the  PFA  system 
is  being  run  should  provide  specific  log-on  and  program  running  procedures. 

3.2  Input  Requirements.  The  user  must  obtain  the  source  code  for  the  system 
being  analyzed,  in  the  format  required  by  the  encoder  being  used,  or  the  source 
code  must  be  prepared  In  correct  format  for  COMPRO  if  PFA  is  being  used  for 
documentation. 

A  standards  file  must  be  prepared  in  a  format  prescribed  by  this  document 
and  In  accordance  with  the  encoder  design. 

The  user  must  answer  the  prompts  output  by  the  PFA  programs,  which  request 
the  names  of  data  and  report  files  and  processing  options. 

A  file  containing  machine/language-specific  source  code  or  compiler  listings 
Is  converted  to  a  common  format,  independent  of  the  machine/language  com¬ 
bination,  creating  a  master  file  used  by  the  generic  report  programs  of  the  PFA 
system. 

When  COMPRO  is  used  to  extract  information  for  documentation,  the  Input  con¬ 
sists  of  specially  formatted  comment  statements.  These  format  statements  may  be 
intermixed  with  executable  statements,  as  encountered  in  a  normal  program, 
though  the  latter  are  not  essential.  Input  which  consists  entirely  of  the  spe¬ 
cial  comment  statements  is  similar  to  a  program  design  language. 

System-specific  encoders  (AUTOxxxx)  require  input  which  is  dependent  on  the 
specific  encoder  design.  This  input  would  normally  consist  of  the  software 
source  code  or  a  compiler  listing  of  the  source.  Encoders  may  require  that  cer¬ 
tain  compiler  options  be  exercised  In  creating  the  listing  file  (e.g.,  specify¬ 
ing  the  option  of  generating  an  assembler-level  listing). 

3.2.1  Source  File.  Figure  3-1  is  an  example  of  a  specially  commented  PFA 
source  module.  TTfe  only  source  file  documented  in  this  manual  is  the  PFA  source 
used  by  COMPRO  to  produce  a  master  file.  COMPRO  processes  specially  formatted 
comments  in  source  code  to  produce  the  master  rile. 

3.2.2  Standards  File.  Each  record  in  the  standards  file  consists  of  eight 
variable  length  fields  separated  by  semicolons.  Figure  3-2  is  a  sample 
standards  file.  The  standards  file  records  and  fields  are  described  in 
appendix  B. 
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SUBROUTINE  READS  ro  -  READ  STANDARDS  PILE 


READ  STD  READS  THE  STANDARDS  FILE  AND  STORES  THE  INFORMATION  FOR 
THE  BASIC  STANDARDS  IN  TV€  STANDARDS  TABLE. 


CALL  PEADSTDO 
VAPlAOtE  LIST 

CE5C  -  S 

SI  v 

tr>« 

MAXV 

MINV 

SICNIF 


3TAN0AR0 

STD 

STDPEC 
SI  01  AO 
TEMP 
WGT 


FILES  USED. 


STANDARD  DESCRIPTION 

EXPRESSION  FOR  CALCULATING  STANDARD 

STANDARD  LA8EL  and  INOEX  INTO  STANDARDS  TABLE 

MAXIMUM  VALUE  TO  MEET  STANDARD 

MINIMUM  VALUE  TO  MEED  STANDARD 

FLAG  INDICATING  WHETHER  A  CHANGE  IN  THE  VALUE  OF 
THIS  STANDARD  SIGNIFIES  A  CODE  OR  DOCUMENTATION 
CHANCE  IN  TVC  MODULE  ( *C.  D ) 

INPUT  VARIABLE  FOR  STANDARDS  FILE 
SEE  STD  DATA  STRUCTURE 
STAWARD  TABLE  ENTRY 
STANDARDS*  table 

INPUT  RECORD  FROM  STANDARDS  FILE 

FLAG  INDICATING  WHETHER  CURRENT  STANDARO  IS  TO  BE 
REPORTED 

*0  -  DO  NOT  REPORT 

>0  -  DO  REPORT 


STANDARDS  FILE  -  FILE  SPECIFYING  PROGRAM  STANDARDS 
CALLS  LIST 


READ  RECORD  AND  GATHER  DATA 


STANOARD  IP.  TEMP  :  ST,  DESC .  ST.  UCT  ST.  MIW:  ST.  MAXV:  ST. 

CIV  ST.3ICNIF  ST. IDX  ST, STDREC  STD 

N  IN.  TEMP  ST.  IDX  .  ST.  DESC:  ST.  WGT  ST.  MINV  ST.  MAXV  ST.  CIV:  ST. 
SIGN  IF  ST. STDREC: STD.  IDX;  IN.  STDTAB<IDX>  STD.  STDTA8:  TA 
LIST 


:  F < RETURN) 


N  *■  0 

STDTAB  ■  TABLE (17) 

TEMP  -  STANDRD  :F(RE 

IOX  -  LIST  (TEMP.  1.  'i  ') 

DESC  -  LIST  ( TEMP,  2»  'i  ') 

WGT  -  LIST  ( TEMP .  3, 

MINV  -  LIST  ( TEMT.  4.  'i  ') 

MAXV  -  LIST  ( TEMP.  3.  'i  '  ) 

GIV  »  LIST  (TEMP.  A.  > 

SICNIF  ■  L  I  ST  (  TEMP .  7.  '»  ') 

STDREC  -  STD(  DESC.  WGT.  MINV.  MAXV.  01 V,  NULL.  SICNIF) 


TEST  FOR  BASIC  ST ANDARD  STORE  INFORMATION  FOR  BASIC  STANDARDS 
IN  STANDARDS  TABLE.  SKIP  USER-DEFINED  STANDARDS 


IDX  -  CONVERT (IDX.  '  INTEGER  * ) 
3TDTAB-:iDX>  -  STDREC 


: F (RSI ) 
: (RSI ) 


K  — 


Figure  3-1.  A  Sample  PFA-Commented  Source  Program 
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Figure  3-2.  Standards  File 


The  following  describes  the  appropriate  vocabulary  for  each  field  of  a 
standards  file  record.  No  field  may  contain  a  sanicolon. 


Field 


Description 


Identifier  Integer  for  basic  standards  (1-141 

Any  other  value  for  user-defined  standards 


Standards  Any  text 

Weighting  Factor  0  for  no  report  on  standard 

1  for  report  on  standard 


Lowest  Permitted  Any  value 
Value 


Highest  Permitted  Any  value  (must  be  greater  than  lowest  permitted 
Value  value) 


Calculation  Null  for  basic  standards.  A  reverse  Polish  expres 

sion  for  user-defined  standards.  The  expression 
may  consist  of  constants,  the  operators 

and  '/',  and  the  values  of  previously  defined 
standards,  referenced  by  the  standard's  ID  in 
parentheses.  For  example,  * (5) ,( 1) ,/ ,'  is  a  legal 
expression. 

Code/Documentation  C  for  code  standards 
Indicator  D  for  documentation  standards 

Standard  Reference  Any  text 


3.2.3  Master  File.  Figure  3-3  is  an  example  portion  of  a  master  file.  The 
master  file  contains  summary  information  on  the  modules  of  the  program  being  an 
alyzed.  Currently  there  are  eleven  record  types  in  the  file,  each  describing 
one  aspect  of  a  module.  These  records  are  grouped  within  the  master  file  ac¬ 
cording  to  the  module  they  describe.  The  aspect  of  a  module  described  by  each 
of  the  record  types  is  as  follows: 

Type  Information 

Header  Record 

0  Library  Routine  Definition 

1  Task  or  Subroutine  Definition 

2  Listing  and  Version  Information 

3  Prologue  Comments 

4  Path  Definition 

5  Subroutine  Calls  Information 

6  Variable  Information 

7  In-Line  Comments 

8  Software  Quality  Information 

9  Entry  Point  Definition 
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The  header  record  has  the  form  "l-H-modname" ,  left-justified.  The  re¬ 
cord  fields  and  their  layouts  are  described  in  appendix  B. 


3.2.4  Selection  File. 


The  selection  file  is  a  list  of  modules  to  be  processed 
contains  one  module  name,  in  the  format  required  by 


the  system  on  which  PFA  is  run.  The  selection  file  cannot  contain  any  blank 


records. 


3.2.5  Terminal  Inputs, 
characters  and  must  be 


All  terminal  inputs  have  a  maximum  length  of  80 
left-justified. 


a.  Option  Specifications.  The  affirmative  response  to  prompts  for  all  op¬ 
tion  requests  is  'YES'  or  ' Y * .  All  other  responses  will  be  Interpreted 
as  negative. 

b.  File  Name  Specifications.  All  file  names  must  be  in  the  format  re¬ 
quired  by  the  system  on  which  PFA  is  run.  The  PATCHANA  request  for  a 
selection  file  name  may  be  answered  with  the  response  'TTY*  as  well  as 
a  file  name. 


c.  File  Name  List  Specification.  The  specification  consists  of  a  list  of 
file  names,  each  in  the  format  specified  by  b.  above,  separated  by 
commas  or  blanks. 


d.  STAMP  Report  Specification.  The  specification  consists  of  a  string  of 
contiguous  letters  as  described  below. 


Letter 


E 

S 

F 

M 

H 


External  Procedures  Report 
Structure  Chart 
Function  List 
Module  List 
HIP0  Charts 


The  letters  may  be  in  any  order.  In  addition,  if  no  specification  is 
made,  the  STAMP  default  is  to  output  all  five  reports. 

e.  STAMP  Variable  Lists.  STAMP  allows  the  user  to  specify  that  certain 
variables  in  the  program  being  analyzed  be  included  or  excluded  from 
processing.  The  responses  to  the  prompts  for  included  or  excluded 
variables  must  have  the  following  format: 
varl:tyl:ul,var2:ty2:u2,...varn:tyn:un, 

where  vari  is  the  variable  name,  tyi  is  an  abbreviation  for  variable 
type,  as  specified  in  the  appropriate  encoder  manual,  and  ui  is  the 
variable  usage,  encoded  as  follows: 

D  Defined 

R  Referenced 

T  Tested 

M  Modified 


A  null  entry  in  one  or  two  fields  means  that  these  fields  will  not  be 
used  as  selection  criteria. 
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3.3  Program  Operations,  The  operation  of  the  PFA  Is  discussed  below. 

3.3.1  COHPRO.  COMPRO  extracts  and  processes  comments  from  a  program  source 
file  for  creating  program  documentation.  Figure  3-4  shows  the  data  flow  between 
COMPRO  and  the  rest  of  the  PFA  system. 

COMPRO  reads  program  source  code  files  which  contain  comments  in  a  specific 
format.  The  information  contained  in  these  comments  is  used  to  create  a  master 
file  which  can  be  processed  by  other  PFA  programs  to  generate  reports  used  for 
program  documentation.  A  listing  of  the  source  code  Is  also  produced. 

3. 3. 1.1  COMPRO  Input  Requirements.  The  only  source  file  documented  in  this 
manual  is  the  PFA  source  code  used  by  COMPRO  to  produce  a  master  file.  COMPRO 
processes  specially  formatted  comments  to  produce  the  master  file.  The 
requirements  for  the  special  comments  are  described  below. 

a.  Prologues. 

(1)  Each  module  has  a  prologue. 

(2)  The  prologue  Is  surrounded  by  asterisks.  This  means  that  the  pro¬ 
logue  must  be  preceded  and  followed  by  a  line  consisting  only  of  a 
string  of  asterisks  and  that  each  line  in  the  prologue  must  begin 
and  end  with  an  asterisk. 

(3)  Every  prologue  contains  as  the  first  non-blank  line: 

TASK 

SUBROUTINE  :  <name>  -  <descr1ption> 

LIBRARY  ROUTINE 

Where,  if  the  module  has  multiple  entry  points,  <name>  is  the  name 
of  the  first  entry  point. 

(4)  Following  item  3  Is  the  module  description: 

AUTHOR: 

DATE  STARTED: 

DATE  LAST  MODIFIED: 

PURPOSE:  <function  of  module> 

DESCRIPTION:  <general  design  description> 

CALL: 

PARAMETER  LIST:  parameters  and  descriptions> 

USER-DEFINED  DATA  STRUCTURES:  structures,  fields,  and 

descriptions> 

VARIABLE  LIST:  <var1ables  and  descr1ptions> 

FILES  USED:  <file  names  and  descr1ptions> 

CALLS: 

LIMITATIONS: 

ERRORS: 

as  there  are  appropriate  data  to  include. 
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(5)  For  each  additional  entry  point  the  module  contains,  (4)  above  is 
followed  by: 

ENTRY  POINT:  <name>  -  <descr1pt1on> 
and  again,  as  many  of  the  items  in  (4)  above  as  appropriate, 
b.  In-Line  Comments 

(1)  All  in-line  comments  are  separated  from  code  by  strings  of 
asterisks. 

(2)  In-line  comments  do  not  contain  '  '. 

(3)  The  In-line  comments  may  contain  psuedo  path  segment 
specifications.  These  specifications  document  the  flow  of  control 
in  a  module  and  are  used  by  COMPRO  and  STAMP  to  create  HIPO 
charts.  If  used,  the  path  segment  specifications  have  the  fol¬ 
lowing  format  and  meaning: 

(a)  The  specification  for  a  path  segment  begins  on  the  first  com¬ 
ment  to  be  included  in  the  segment. 

(b)  The  specification  is  the  rightmost  item  on  the  comment  line. 

(c)  The  specification  is  of  the  form: 

Mnl.n*,.  ..][£] 

where  m  is  the  optional  node  label  for  the  start  of  the  path 
segment,  ni  are  the  optional  node  labels  to  which  the  segment 
branches,  and  E  indicates  branch  to  exit.  If  the  from  node 
label  Is  null,  the  from  node  label  will  be  assumed  to  be  the 
current  node  count  for  this  module.  If  the  to  node  labels 
(including  E)  are  null,  the  to  node  label  wiTT  be  assumed  to 
be  the  current  node  count  for  this  module  plus  one.  If  this 
path  segment  is  an  entry  point  for  the  module  but  is  not  the 
first  entry  point  to  the  module,  m  must  be  the  name  of  the 
entry  point. 

(d)  The  last  path  specification  in  a  module  has  a  to  node 
specified. 

(4)  All  referenced  and  modified  variables  appearing  in  a  psuedo  path 
segment  are  listed  in  comments  within  the  path  segment  for  use  by 
COMPRO  and  STAMP.  If  there  is  no  path  segment  specification,  all 
referenced  and  modified  variables  for  the  module  are  listed.  Com¬ 
ments  listing  referenced  or  modified  variables  have  the  respective 
formats: 

INPUT :  varl[:type],var2[:type],...vari[:type]. 


...varn[:type] 


21 


OUTPUT :  varl[:type],var2[:type],...vari[:type] 


...varn[:type] 

where  type  is  optional  and  is  an  abbreviation  for  the 
variable's  type.  In  the  case  of  SNOBOL  the  types  are  abbreviated 
as  follows: 

TYPE 


String 
Integer 
Real  Number 
Pattern  Structure 
Array 
T  able 

Created  Name 
Unevaluated  Expression 
Object  Code 
Programmer-defined 
External 
Input 
Output 

Several  lists  may  be  included  in  one  path. 

(5)  All  subroutines  called  in  a  pseudo  path  segment  are  listed  in  com¬ 
ments  within  the  path  segment  for  use  by  COMPRO  and  STAMP.  If 
there  is  no  path  segment  specification,  all  subroutines  called  in 
the  module  are  listed.  Comments  listing  the  calls  have  the 
format: 

calls:  calll,  call 2 , . . . call i , 


ABBREVIATIONS 

ST 

IN 

RE 

PA 

AR 

TA 

NA 

UN 

CO 

Data  type  name 

EX 

IP 

OP 


...calln 

Several  lists  may  be  included  in  one  path  segment 

3.3.1 .2  COMPRO  Initiation  Procedures.  COMPRO  may  be  run  from  any  interactive 
terminal  connected  to  the  VAX.  Assuming  that  the  user  has  logged  onto  the  VAX 
with  the  correct  password,  he  can  run  COMPRO  by  entering  the  command: 

$  PFA 

(respond  to  menu  prompt  for  COMPRO) 

COMPRO  will  then  prompt  the  user  for  the  following  information.  The  user's 
response  is  underscored. 
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COMMAND/RESPONSE 


EXPLANATION 


ENTER  SOURCE  FILE  NAME 
M.SNO 


The  entered  source  file  name  is  the  name 
of  the  source  file  to  be  processed  by 
COMPRO. 


ENTER  LIST  FILE  NAME 
M.LST 


ENTER  MASTER  FILE  NAME 
M.MST 


The  entered  list  file  name  is  the  name  of  the 
disk  file  containing  the  output  source 
listing. 

The  entered  master  file  name  is  the  name  of 
the  output  master  file. 


COMPRO  will  then  complete  the  master  file  generation  with  no  further 
prompts. 


3. 3. 1.3  Files  Used  in  COMPRO  Processing.  COMPRO  dots  not  use  temporary  files. 

3.3.1 .4  COMPRO  Recovery  and  Error  Correction  Procedures.  COMPRO  indicates  the 
following  errors: 

a.  Messaqe:  "ERR10:  ERROR  PROCESSING  LINE  IN  MODULE 

"( line>  " 

This  means  that  COMPRO  has  found  a  line  in  the  PFA  source  with  an  un¬ 
expected  format.  The  message  indicates  an  error  within  COMPRO,  and 
processing  terminates. 

b.  Message:  "ERR20:  UNEXPECTED  END  OF  FILE  IN  MODULE _ " 

This  means  that  COMPRO  has  found  an  end  of  i’le  while  reading  a  multi- 
line  list.  The  message  indicates  an  error  in  the  PFA  source.  Process¬ 
ing  terminates. 

In  the  event  of  a  hardware  error  which  terminates  the  program,  the  program 
must  be  restarted  from  the  beginning.  In  the  event  of  a  fatal  software  error 
while  running  COMPRO,  all  files  must  be  checked  to  ensure  they  exist  and  are  not 
attached  to  another  program;  COMPRO  is  then  rerun. 

3. 3. 1.5  COMPRO  Limitations 


a.  Comments  in  the  input  source  listing  may  not  contain  '  ’  „ 

b.  Prologues  must  be  delimited  by  a  string  of  more  than  40  asterisks  and 
other  comments  cannot  be. 

c.  In-line  comments  must  be  separated  from  code  by  strings  of  asterisks. 

3. 3. 1.6  COMPRO  Sample  Outputs.  Figure  3-5  presents  a  sample  from  a  master  file 
output  by  COMPRO"  The  layout  of  the  master  file  and  the  meaning  of  each  field 
is  described  in  appendix  3.  COMPRO  does  not  output  a  value  for  the  following 
fields  described  in  appendix  8:  Source  Sequence  Number,  Version  Information, 
Quantifiers  1,  2  and  3,  and  Start,  End,  and  Branch  Sequence  Numbers.  In  ad¬ 
dition,  COMPRO  outputs  only  one  software  quality  parameter  to  the  type  8  record. 
This  parameter  is  the  number  of  non-comment  lines  per  module. 


REPORT  FILE  -|wj.4IS  FILE  CONTAINS  THE  STRUCTURE  COMPARISON 
REPORT. 
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A  reformatted  source  file  output  by  COMPRO  is  similar  to  figure  3-1  but 
includes  page  numbers  and  page  headers.  The  page  numbers  provided  with  this 
listing  are  referenced  by  some  of  the  reports  produced  by  STAMP,  SOFTPRO,  SYS- 
TRUCT,  and  PATCHANA.  The  page  headers  indicate  the  report  is  unclassified. 

3.3.2  STAMP.  STAMP  provides  program  structure  analysis.  Figure  3-6  shows  the 
data  flow  between  STAMP  and  the  rest  of  the  PFA  system. 

The  STAMP  program  reads  the  Master  File  end  generates  reports  on  the  overall 
system  under  analysis  to  aid  in  modeling  that  system  and  to  provide  informa'.ion 
about  the  structure  of  that  system.  STAMP  provides  five  reports,  as  follows: 

External  Procedure  Report 
Structure  Cha^t 
Function  List 
Module  List 
HIPO  Diagram 

3. 3. 2.1  STAMP  Input  Requirements.  The  encoder  (AlfTOxxxx)  or  COMPRO  must  have 
been  run  previously  to  produce  the  master  file  needed  as  input  to  STAMP. 

3. 3. 2. 2  STAMP  Initiation  Procedures.  STAMP  may  be  run  from  any  interactive 
terminal  connected  to  the  VAX.  Assuming  that  the  user  has  logged  onto  the  VAX 
with  the  correct  password,  he  can  run  STAMP  Dy  entering  the  command: 
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STAMP  will  then  prompt  the  user  for  the  following  Information: 


COMMAND/RESPONSE 

ENTER  MASTER  FILE  NAME: 
Hl.MST 

ENTER  REPORT  FILE  NAME: 

M.REP 

DO  YOU  WANT  ALL  THE  REPORTS? 
NO 


SELECT  REPORTS  (E:  EXTERNAL, 

S:  STRUCTURE,  F:  FUNCTION, 

M:  MOOULE,  H:  HIPO) 

SH 

DO  YOU  WANT  SPECIAL  PROCESSING? 
YES 


DO  YOU  WANT  TIMING  MINIMIZATION? 
YES 


DO  YOU  WANT  PATH  PRUNING? 
YES 


DO  YOU  WANT  DEBUG  OUTPUT? 

NO 

DO  YOU  WANT  FULL  STRUCTURE  CHART? 
YES 


EXPLANATION 

This  Is  the  waster  file  to  be  processed 
In  this  STAMP  run. 

This  is  the  name  of  the  disk  file  to  con¬ 
tain  the  output  STAMP  reports. 

'YES'  or  * Y*  sets  the  default  to  produce 
all  of  the  reports,  otherwise  the  user 
must  select  the  desired  reports.  In  the 
example,  the  negative  response  indicates 
specific  reports  are  desired. 

The  request  to  select  reports  allows  the 
user  to  choose  the  reports  he  desires. 

In  the  example,  the  structure  chart  and 
HIPO  charts  have  been  selected. 

'NO'  or  'N*  if  additional  options  are  not 
desired.  If  'YES',  user  must  answer 
prompts  to  select  desired  processing. 

Timing  minimization  provides  Information 
for  timing  analysis  using  the  path 
segment  descriptions  in  the  HIPO  charts. 
If  minimization  is  requested,  the 
quantifiers,  consisting  of  such  values  as 
execution  time  or  number  of  executable 
lines  of  code  reported  for  each  path 
segment  In  the  HIPO  chart,  will  show  only 
the  difference  in  values  between  paths 
from  the  same  node. 

Provides  additional  information  for  tim¬ 
ing  analysis  using  the  path  segment  des¬ 
criptions  in  the  HIPO  charts.  If  "YES" 
in  addition  to  timing  minimization,  ref¬ 
erences  to  nodes,  all  of  whose  path 
quantifiers  are  zero,  are  deleted  and 
paths  reconnected  as  necessary. 

Consists  of  node  data  output  to  the  file 
STAMP  .TMP. 

The  full  structure  chart  includes  module 
descriptions  along  with  the  module 
names. 


COMMAND/ RESPONSE 


EXPLANATION 


DO  YOU  WANT  VARIABLE  PROCESSING? 
YES 

rFJTER  VARIABLES  TO  BE  INCLUDED: 
VAR1 : IN :M,VAR1 : IN :R 


ENTER  VARIABLES  TO  BE  EXCLUDED: 
VAR2: IN :D 


Variable  processing  is  used  to  include  or 
exclude  specified  variables  from  process¬ 
ing.  The  variables  to  be  included  or 
excluded  must  be  specified  at  the  next 
two  prompts.  The  first  prompt,  for 
included  variables,  deiaults  to  all. 

The  second  prompt,  for  excluded 
variables,  defaults  to  none. 


The  STAMP  program  will  then  complete  the  report  generation  with  no  further 
prompts. 


3.3. 2. 3  Files  Used  in  STAMP  Processing.  Two  temporary  files  are  used  in  STAMP 
processing,  STAMP.TMP  and  STAMP1.TMP. 

3. 3. 2. 4  STAMP  Recovery  and  Error  Conditions.  STAMP  provides  the  diagnostic 
message:  "BAD  MAP  FOR  ~tT~l  Thi  s  means  that  there  is  a  to  label  without  a 
corresponding  from  1 abel  or  that  the  from  or  to  label  is  null  for  a  path  datum 
In  the  master  file.  This  results  from  incomplete  path  structure  generated  by 
the  encoder  or  from  dead  code  in  the  source  code  being  analyzed. 

In  the  event  of  a  hardware  error  which  terminates  the  program,  the  program 
must  be  restarted  from  the  beginning. 

In  the  event  of  a  fatal  software  error  while  running  STAMP,  the  user  should 
check  to  make  sure  all  files  exist  and  are  not  attached  to  another  program,  and 
rerun  STAMP. 

3. 3. 2. 5  STAMP  Limitations.  STAMP  may  cause  memory  thrashing  if  there  are  more 
than  1000  path  records  ir  any  module  or  if  there  are  more  than  300  path  records 
in  any  module  and  path  pruning  is  being  used. 

3. 3. 2. 6  STAMP  Sample  Outputs. 

a.  External  Procedure  Report  (see  figure  3-7).  This  report  shows  all  calls 
to  external  procedure  in  the  program  being  analyzed,  where  an  external 
procedure  is  any  module  not  appearing  anywhere  in  the  file.  The  calls 
are  shown  in  the  order  in  which  they  appear  in  the  file. 

b.  Structure  Chart  (see  figure  3-8).  The  structure  chart  shows  the  calling 
structure  of  the  program  being  analyzed.  Each  call  statement  occurring 
anywhere  in  the  program  is  shown,  along  with  the  “level"  of  the  call. 

The  main  module  is  listed  first,  with  a  call  level  of  zero.  After  each 
module,  all  modules  called  by  that  module  are  listed,  at  the  next- 
highest  call  level. 

c.  Function  List  (see  figure  3-9).  The  function  list  is  a  list  of  all 
task-level  modules  in  the  system.  The  name  of  the  module,  a  description 
of  the  module,  and  version  information  are  provided. 


EXTERNAL  PROCEDURES  REPORT 
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Figure  3-7.  STAMP  External  Procedures  Report 


STRUCTURE  CHART  FOR  STAMP 
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Figure  3-8.  STAMP  Structure  Chart 
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Figure  3-9.  STAMP  Function  List 


d.  Module  List  (see  figure  3-10).  This  report  lists  all  subroutines  and 
entry  points  in  the  program  being  examined.  It  provides  the  following 
information  for  each  module: 

(1)  Module  name 

(2)  Type  of  module:  S  =  subroutine 

T  =  task 
E  3  entry  point 

(3)  Page  number  refers  to  the  page  on  which  this  module  can  be 
found  in  the  listing  provided  by  AUTOxxxx. 

(4)  Description  of  module  is  taken  from  the  first  line  of  the 
module. 

(5)  Call  level  shows  both  the  minimal  (top)  and  maximal  (bottom) 
Mdi stance"  of  the  module  from  the  main  program  as  determined 
from  the  structure  chart. 

(6)  Version  information  is  taken  directly  from  the  master  file. 

e.  HI PO  Diagram  (see  figure  3-11).  This  chart  shows,  for  each  module,  the 
following  information:  module  name,  a  list  of  all  modules  which  call 
this  module;  a  description  of  the  module;  and  a  list  of  all  program 
segments  of  the  module,  where  a  program  segment  is  a  contiguous  group  of 
records  which  contains  no  branches  except  possibly  on  the  last  record  of 
the  segment. 

For  each  segment,  the  following  are  shown: 

(1)  Inputs:  This  is  a  list  of  all  variables  which  are  referenced 
within  the  segment. 

(2)  Processing:  This  is  expressed  by  the  string: 

11:  label^S^)  labelj^):  <f  i  rstl  ine-lastl  ine>  branchpoint  11 
is  a  sequence  number. 

Label j  is  the  line  number  of  the  first  record  of  the  seg¬ 
ment. 

Si  is  the  segment  number.  (These  are  assigned  sequentially 
in  the  order  in  which  they  occur  in  the  module  being 
sc rutinized) . 

Label 2  is  the  line  number  of  the  segment  to  which  program 
control  is  transferred  after  this  segment  of  instructions  has 
been  executed.  If  program  control  can  be  transferred  to  more 
than  one  segment  from  this  segment  (such  as  in  a  conditional 
branch),  then  the  information  for  this  segment  will  be  re¬ 
peated  once  for  each  branch  point.  (That  is,  only  11, 
label2»  S2»  and  branchpoint  will  change). 
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Figure  3-10.  STAMP  Module  List 
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Sj  Is  the  segment  number  to  which  control  is  transferred. 

Flrstl ine-lastl ine  shows  the  first  and  last  records  of  this 
segment. 

Branchpoint  is  the  record  to  which  control  is  transferred. 

The  first  line  is  followed  by  a  second  line  with  three 
values: 

Oi :  This  is  the  computer  CPU  time  this  segment  consumes. 

Q2  is  the  number  of  assembly  statements  in  the  segment;  and 
Q3  is  the  number  of  storage  words  in  the  segment. 

(3)  Outputs:  This  Is  a  list  of  all  variables  which  are  modified 
by  the  segment. 

3.3.3  SOFTPRO.  SOFTPRO  performs  software  quality  analysis.  Figure  3-12  shows 
the  data  flow  between  SOFTPRO  and  the  rest  of  the  PFA  system. 

SOFTPRO  reads  the  master  file  and  software  standards  file  and  generates  two 
reports.  The  software  profile  reports  for  each  module  list  the  violations  of 
software  standards  as  defined  by  the  user  in  the  software  standards  file.  The 
profile  summary  contains  the  list  of  standards,  the  number  and  percent  of  mod¬ 
ules  meeting  each  standard,  the  number  and  percent  of  modules  violating  each 
standard,  and  the  reference  to  the  regulation  containing  each  standard. 

3. 3. 3.1  SOFTPRO  Input  Requirements.  The  encoder  program  AUTOxxxx  must  have 
been  i  un  to  create  the  master  file.  The  software  standards  file  must  also  ha  -e 
been  created. 


3. 3. 3.2  SOFTPRO  Initiation  Procedures.  To  run  the  SOFTPRO  program,  the  ust' 
should  enter,  from  an  interactive  terminal  connected  to  the  VAX,  the  command. 

S  PFA 

(respond  to  menu  prompt  for  SOFTPRO) 

SOFTPRO  will  then  prompt  the  user  for  the  following  information: 


COMMAND/RESPONSE 

ENTER  THE  MASTER  FILE  NAME: 

Ml.MST 

ENTER  THE  STANDARDS  FILE  NAME: 

M1  STD 

DO  YOU  WANT  THE  FULL  REPORT  ( Y/N) ? 
Y 


EXPLANATION 

This  is  the  name  of  the  master  file  that 
will  be  processed  during  this  run. 

Tnis  is  the  name  of  the  standards  file  to 
be  referenced  during  this  run. 

A  full  report  includes  a  software 
standards  violations  details  report  for 
each  module  as  well  as  the  software 
standards  violations  summary  report  for 
the  entire  program. 


SOFTPRO  will  then  proceed  to  generate  the  software  profile  reports. 
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Figure  3-12.  SOFTPRO  Data  Flow 


G" 


3. 3. 3. 3  Files  Used  In  SOFTPRO  Processing.  The  report  output  from  SOFTPRO  is 

P  I  dUCU  III  dll  ic  ndliCU  rl\wi  iUU«l\Ur  • 

3. 3. 3. 4  SOFTPRO  Recovery  and  Error  Correction  Procedures.  SOFTPRO  has  the  fol- 
1  owing  error  conditions: 

a.  Message:  "STANDARD  REFERENCE  IN  STANDARD  LINE _ "  IS  NOT  FOUND 

This  means  that  a  standard  reference  in  the  calculation  field  of  the 
indicated  line  of  the  standards  file  cannot  be  found. 

b.  Message:  "IN  STANDARDS  FILE,  ERROR  IN  SPECIFYING  CALCULATION  FOR 

STANDARD  LINE _ " 

This  means  that  the  calculation  field  of  the  indicated  line  of  the 
standards  file  Is  In  error. 

c.  Message:  "IN  THE  STANDARD  FILE,  LINE  _  SPECIFIES  A  CALCULATION  FOR 

A  BASIC  STANDARD" 

This  means  ^hat  for  the  indicated  line  in  the  standards  file,  the 
standard  number  is  between  1  and  14,  indicating  that  it  is  a  basic 
stindard,  but  the  calculation  field  contradicts  that  by  providing  a 
calculation. 

d.  Message:  "IN  THE  STANDARDS  FILE,  LINE  _ SPECIFIES  A  STANDARD  WHICH 

IS  NOT  BASIC  BUT  IT  HAS  NO  CALUCLATION" 

This  means  that  for  the  indicated  line  in  the  standards  file  the 
standard  number  Is  not  between  1  and  14,  indicating  that  it  is  not  a 
basic  standard,  but  there  was  no  calculation  using  basic  standards 
Included  in  the  calculation  field. 

3. 3. 3. 5  SOFTPRO  Limitations, 

a.  A  maximum  of  14  basic  standards  can  be  entered  on  the  standards  file.  A 
basic  standard  is  one  directly  calculated  by  the  encoder,  AUTOxxxx.  It  must 
have  an  identifier  of  from  1  to  14  in  the  standards  file. 

b.  Module  names  must  be  from  1  to  10  characters  long. 

c.  The  maximum  number  of  standards  allowed  to  be  input  is  30. 

d.  The  maximum  number  of  operators  allowed  in  a  standard  expression  is  20. 

e.  The  maximum  number  of  subroutines  allowed  in  the  master  file  is  200. 

The  last  three  limitations  are  program  parameters  which  may  be  increased  by 

modifying  the  parameters  in  the  source  code  and  recompiling  and  linking. 

3. 3. 3. 6  SOFTPRO  Sample  Outputs. 

a.  Software  Standards  Violations  Details  Report  (see  figure  3-13).  This 
report  lists  each  module  of  the  file  being  analyzed.  For  each  module 
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Figure  3-13.  SOFTPRO  Standards  Violations  Details  Report 
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Figure  3-14.  SOFTPRO  Standards  Violations  Summary  Report 
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Figure  3-15.  SQFTPRO  Quality  Values  Report 
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Figure  3-15.  SOFTFRO  Quality  Values  Report  (Cont.) 


all  standards  defined  In  the  software  standards  file  which  have  been 
violated  by  that  module  are  listed.  The  value  of  the  standard 
calculated  for  that  module  Is  shown,  along  with  the  permitted  range  of 
the  standard. 

b.  Software  Standards  Violations  Summary  Report  (see  figure  3-14).  For 
each  standard  defined  in  the  software  standards  file,  the  number  and 
percentage  of  modules  which  met  that  standard  are  shown,  and  the  number 
and  percentage  of  modules  which  violated  that  standard  are  shown.  Ad¬ 
ditionally,  the  quality  values  are  summarized  for  all  the  modules  and 
listed  individually  for  each  module  (see  figure  3-15). 

3.3.4  SYSTRUCT.  SYSTRUCT  provides  analysis  of  system  configuration  changes. 
Figure  3-1$  shows  the  data  flow  between  SYSTRUCT  and  the  rest  of  the  PFA  system. 

SYSTRUCT  reads  two  master  files  representing  different  versions  of  the 
software  system  under  analysis.  The  SYSTRUCT  report  lists  changes  in  variables 
used  by  each  module,  changes  in  software  quality  parameters  (the  ones  reported 
by  SOFTPRO),  and  modules  which  have  been  added  to  or  deleted  from  the  current 
version  of  the  software  being  analyzed.  The  changes  are  of  two  types:  those 
affecting  executable  code  and  those  affecting  code  documentation.  When  changes 
affect  executable  code,  a  selection  file  containing  a  list  of  module  changes  is 
generated  for  use  by  PATCHANA. 

3. 3. 4.1  SYSTRUCT  Input  Requirements.  SYSTRUCT  requires  two  master  files  as 
Input,  one  for  each  version  of  the  program  to  be  analyzed.  See  paragraph  3.2.3 
and  appendix  B  for  the  master  file  description. 

SYSTRUCT  also  requires  a  standards  file  for  the  standards  file  description. 

A  description  of  the  file  and  its  layout  is  given  in  paragraph  3.2.3  and  in  ap¬ 
pendix  B. 

3. 3.4. 2  SYSTRUCT  Initiation  Procedures.  Following  is  a  description  of  a  SYS- 
TRUCT  terminal  session. 


SYSTRUCT  may  be  run  from  any  Interactive  terminal  connected  to  the  VAX.  As¬ 
suming  that  the  user  has  logged  onto  the  VAX  with  the  correct  password,  he  can 
run  SYSTRUCT  by  entering  the  following  command: 


SPFA 

(respond  to  menu  prompt  for  SYSTRUCT) 

SYSTRUCT  will  then  prompt  the  user  for  the  following  information: 


COMMAND/RESPONSE 


EXPLANATION 


ENTER  OLD  MASTER  FILE  NAME,  WITH 

EXTENSION 

HOLD.MST 

ENTER  NEW  MASTER  FILE  NAME,  WITH 

EXTENSION 

MNEW.MST 


The  entered  old  and  new  master  file  names 
are  the  names  of  the  master  files  for 
the  old  and  new  versions  of  the  programs 
to  be  analyzed. 
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COMMANO/RESPONSE 


EXPLANATION 


ENTER  REPORT  FILE  NAME 
M.REP 


ENTER  STANDARDS  FILE  NAME 
M.STD 


ENTER  SELECTION  FILE  NAME: 
M.SEL 


DO  YOU  WANT  STRUCTURE  CHART? 
YES 


The  entered  report,  file  name  Is  the  name 
of  the  disk  file  to  contain  the  output 
SYSTRUCT  report. 

The  entered  standards  file  name  is  the 
name  of  the  standards  file  to  be  ref¬ 
erenced  during  this  run. 

The  entered  selection  file  name  Is  the 
name  of  the  disk  file  to  contain  the  out¬ 
put  list  of  modules  having  probable  code 
changes. 

If  requested,  a  structure  chart  for  the 
new  version  of  a  module  will  be  output  in 
the  report  on  each  module. 


SYSTRUCT  will  then  complete  the  report  generation  with  no  further  prompts. 

3. 3. 4. 3  Files  Used  in  SYSTRUCT  Processing.  No  temporary  files  are  used. 

3. 3.4. 4  SYSTRUCT  Recovery  and  Error  Correction  Procedures.  In  the  event  of  a 
hardware  error  which  terminates  the  program,  the  user  must  start  the  program 
from  the  beginning.  In  the  event  of  a  fatal  software  error  while  running  SYS¬ 
TRUCT,  the  user  should  check  to  make  sure  all  files  exist  and  are  not  attached 
to  another  program,  and  rerun  SYSTRUCT. 


3. 3. 4. 5  SYSTRUCT  Limitations.  No  limitations  are  known. 


3. 3.4. 6  SYSTRUCT  Sample  Outputs.  Figure  3-17  presents  a  sample  portion  of  a 
SYSTRUCT  report.  This  report  shows,  at  module  level,  differences  in  subroutine 
calls,  number  of  paths  containing  subroutine  calls,  and  software  quality  metrics 
between  two  versions  of  a  system.  The  report  consists  of  a  series  of  mini¬ 
reports,  one  for  each  module  which  has  changed  between  versions.  Each  mini¬ 
report  has  two  to  four  parts.  First,  the  report  begins  with  a  header  line  con¬ 
taining  the  module  name,  description,  and  starting  page  numbers  of  both  versions 
in  the  encoder  listings.  Second,  the  report  contains  an  optional  structure 
chart,  similar  to  the  STAMP  structure  chart,  for  the  new  version  of  the  module. 
Third,  the  report  contains  a  list  of  the  differences  between  the  versions  of  the 
module.  The  list  is  headed  by  the  version  information  for  the  old  and  new  mod¬ 
ules.  The  list  contains  common,  added,  and  deleted  subroutines  if  changes  in 
subroutine  calls  have  been  made,  and  software  metrics  with  values  that  differ 
between  versions.  Fourth,  the  optional  last  line  in  the  report  describes  the 
probable  level  of  change  in  the  module.  If  a  software  code  metric  value  has 
changed,  a  code  level  change  is  indicated;  if  a  software  documentation  metric 
value  has  changed,  a  documentation  level  change  is  indicated. 

3.3.5  PATCHANA.  PATCHANA  performs  software  patch  (source  code  change)  anal- 
ysis.  Figure  3-18  shows  the  data  flow  between  PATCHANA  and  the  rest  of  the  PFA 
system. 
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OLD  MASTER  /  /NEW  MASTER  /  /  SELECTION 
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Figure  3-18.  PATCHANA  Data  Flow 


PATCHANA  reads  two  master  files  or  subsets  of  master  files  representing  two 
versions  of  the  software  being  analyzed.  Selection  can  be  made  interactively  or 
via  the  selection  file,  which  contains  a  list  of  modules  to  be  compared.  The  re¬ 
port  lists  the  path  segment  structure  for  both  versions  side  by  side  and 
indicates  (with  codes  and  arrows)  the  location  of  differences  and  what  was 
changed  for  each  version.  When  structural  differences  occur,  the  differences 
are  flagged  from  their  start  either  through  the  remainder  of  the  module  or  to 
the  point  where  the  structures  of  the  two  versions  are  congruent.  PATCHANA 
finds  differences  in  structure,  subroutine  calls,  variable  usage,  and  the  three 
quantifiers. 

3. 3. 5.1  PATCHANA  Input  Requirements.  PATCHANA  requires  as  Input  two  master 
files,  or  subsets  of  two  master  files,  one  for  each  version  of  the  system  to  be 
analyzed.  See  paragraph  3.2.3  and  appendix  B  for  the  master  file  description. 

If  a  subset  of  a  master  file  is  used,  it  must  contain  the  data  for  all  the  mod¬ 
ules  to  be  analyzed. 

PATCHANA  also  requires  as  input  a  list  of  modules  to  be  analyzed.  This  list 
may  be  entered  interactively,  as  described  below,  or  the  list  may  be  Input  as  a 
selection  file,  as  described  in  paragraph  3.3.3. 

3. 3. 5. 2  PATCHANA  Initiation  Procedures.  PATCHANA  may  be  run  from  any  Inter¬ 
active  terminal  connected  to  the  VAX.  Assuming  that  the  user  has  logged  onto 

the  VAX  with  the  correct  password,  he  can  run  PATCHANA  by  entering  the  following  . 
command: 


$  PFA 

(respond  to  menu  prompt  for  PATCHANA) 


PATCHANA  will  then  prompt  the  user  for  the  following  information: 


PROMPT /RESPONSE 


EXPLANATION 


ENTER  OLD  MASTER  FILE  NAME: 
MOLD.MST 


ENTER  NEW  MASTER  FILE  NAME: 
NEW.MST 


This  Is  the  name  of  the  subset  of  the 
master  file  containing  information  on  the 
old  versions  of  the  modules  to  be 
processed. 

New  second  master  file  to  compare  against 
old  first. 


ENTER  REPORT  FILE  NAME: 

MST .LST  Report  file  where  the  results  of  the 

change  analysis  are  stored. 


3. 3. 5. 3  PATCHANA  Limitations.  PATCHANA  cannot  process  multiple  entry  points. 

3. 3. 5. 4  PATCHANA  Sample  Outputs.  Figure  3-19  is  a  sample  PATCHANA  report. 

This  report  shows  path  level  differences  between  module  versions,  the  report 
consists  of  a  series  of  mini-reports,  one  for  each  module.  Each  mini-report 
consists  of  two  parts,  a  header,  and  a  patch  comparison  list.  The  header  con¬ 
tains  the  module  name  and  description.  The  list  consists  of  three  sets  of  col¬ 
umns:  a  description  of  the  old  paths,  a  description  of  the  new  paths,  and  a  de¬ 
scription  of  the  differences  between  the  two  paths. 
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Figure  3-19.  PATCHANA  Report 


The  description  of  the  differences  between  the  paths  Is  first.  The  de¬ 
scription  consists  of  a  series  of  flags  Indicating  the  types  of  differences 
found.  The  flags  are: 

Q[l][2][3]  Differences  in  quantif 1er( s)  1  and/or  2  and/or  3 
P  Difference  In  successor  paths 

N  Difference  In  successor  nodes 

S  Difference  In  subroutine  calls 

V  Difference  In  variable  lists 


If  no  differences  are  found,  this  column  will  be  blank.  This  description  of 
the  differences  between  paths  will  be  repeated  for  every  line  of  the  path  de¬ 
scriptions. 


IT 


The  description  of  the  old  paths  is  second,  and  the  description  of  the  new 
paths  Is  third.  The  descriptions  contain  the  same  information  and  have  the  fol¬ 
lowing  format:  Each  description  is  headed  by  the  version  information  for  the 
module  being  described.  This  header  is  followed  by  six  subcolumns.  The  first 
column  contains  the  number  of  the  path  being  described.  The  second  column  con¬ 
tains  the  label  and,  in  parentheses,  the  number  of  the  from  node  for  the  path. 
The  third  column  contains  the  label  and,  in  parentheses,  the  number  of  the  to 
node  for  the  path.  If  requested,  the  second  and  third  columns  may  contain 
source  sequence  numbers  rather  than  labels.  Columns  four  through  six  contain 
the  values  of  quantifiers  1,  2,  and  3,  respectively.  Following  the  column 
Infonnation  for  each  path,  the  path  description  contains  a  list  of  the  sub¬ 
routines  called  in  the  path  and  a  list  of  tne  variables  used  in  the  path.  Each 
variable  entry  in  the  variable  list  consists  of  the  variable  name  followed  by  a 
colon,  optionally  followed  by  variable  type,  followed  by  a  colon,  followed  by 
variable  use.  The  variable  use  entry  must  be  one  of  the  following: 


D  Defined 

R  Referenced 

T  Tested 

M  Modified 


3.4  Utilization  of  System  Outputs. 

3.4.1  STAMP  Reports. 

a.  The  external  procedures  report  (figure  3-7)  lists  subroutines  which  are 
called  but  are  not  part  of  the  software  being  analyzed.  These  sub¬ 
routines  are  usually  a  part  of  libraries  supplied  with  the  operating 
system  or  compiler  for  the  system  being  analyzed.  If  subroutines  are  in 
the  list,  and  should  be  in  the  software  being  analyzed,  then  those  sub¬ 
routines  are  missing. 

b.  The  structure  chart  (figure  3-8)  shows  the  subroutine  call  hierarchy, 
starting  from  task  or  program  level  (level  0)  through  each  level  of  suo- 
routine  call  to  the  lowest  level.  The  subroutines  called  by  the  task 
level  programs  are  level  one,  the  subroutines  they  call  are  level  two, 
etc.  Each  level  is  shown  on  the  chart  indented  to  the  right  of  the 
higher  level.  The  subroutine  name  is  given  and,  as  an  option,  a  brief 
description  is  given.  External  subroutines  and  recursive  subroutines 
are  marked  as  such. 
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c.  The  function  list  (figure  3-9)  lists  the  highest  level  procedures  in 
the  software  under  analysis,  i.e.,  at  the  program  or  task  level, 
procedures  which  are  not  called  as  subroutines. 

d.  The  module  list  (figure  3-10)  lists  all  procedures  and  entry  points  in 
alphabetical  order.  The  columns  in  the  report  are  procedure  name, 
task/ subroutine  flag,  page,  description,  top  call  level,  bottom  call 
level,  and  version  information. 

The  procedure  name  contains  the  name  of  the  task,  subroutine,  or  entry 
point.  The  task/subroutine  flag  shows  an  "S’*  if  the  procedure  is  a 
subroutine,  a  "T"  If  the  procedure  is  a  task  or  is  not  called  by  an¬ 
other  procedure,  or  an  “E"  If  the  procedure  Is  an  unused  or  uncalled  en¬ 
try  point  in  a  module  with  multiple  entry  points.  The  page  and  de¬ 
scription  are  supplied  by  the  master  file,  as  determined  by  the  encoder. 
The  top  call  level  is  the  highest  level  on  which  the  procedure  is 
called.  This  is  zero  for  a  task  or  unused  entry  point,  one  for 
procedures  called  by  them,  etc.  The  bottom  level  is  the  lowest  level  at 
which  a  subroutine  is  called.  Again,  tasks  and  unused  entry  points  have 
a  level  of  zero.  Procedures  which  have  little  or  no  difference  between 
top  call  level  and  bottom  call  level  are  most  likely  a  "single  use"  or 
"limited  use"  routine.  If  there  is  much  difference  between  the  top  call 
level  and  the  bottom  call  level,  the  procedure  is  more  likely  a  utility 
routine.  The  version  information  is  taken  directly  from  the  -laster 
fil  e. 

e.  The  HIPO  chart  (figure  3-11)  gives  detailed  information  about  each 
procedure.  "Subroutine  Definition"  or  "Task  Definition"  heads  each 
procedure  listing.  This  is  followed  by  the  procedure  name,  short  de¬ 
scription,  page,  and  version  information,  all  of  which  are  extracted 
from  the  master  file.  These  are  followed  by  a  list  of  modules  calling 
the  procedure;  this  is  not  shown  if  the  procedure  is  a  task.  Next  is  a 
list  of  modules  called  by  the  procedure;  this  is  only  shown  if  the 
procedure  makes  subroutine  calls.  Next  is  the  list  of  entry  points  (not 
shown  on  example).  This  list  is  produced  only  if  the  procedure  contains 
multiple  entry  points.  The  prologue  copied  from  the  master  file  fol¬ 
lows.  Then,  the  inputs  column  lists  the  variables  which  are  referenced 
(but  not  modified)  by  the  procedure.  Variable  type  information  is 
included.  Next,  the  processing  column  has  a  description  of  each  path, 
using  both  labels  produced  by  the  encoder,  and  sequence  numbers  from  the 
original  source  as  processed  by  the  encoder.  This  allows  the  user  to 
see  how  the  structure  represented  in  the  processing  column  relates  to 
the  original  source  code.  The  processing  column  also  contains  comments 
extracted  from  the  original  source  by  the  encoder;  quantifiers,  which 
are  quantities  such  as  time,  statanent  counts,  etc.;  and  a  list  of  sub¬ 
routine'’  called  on  each  path.  Finally,  the  outputs  column  lists  all  of 
the  variables,  with  their  variable  type  information,  which  are  modified 
on  each  path.  The  inputs,  processing,  and  outputs  columns  can  be  used 
to  check  the  HIPO  charts  in  the  Program  Design  Document  CPCI’s  for  ac¬ 
curacy. 
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a.  The  SOFTPRO  detailed  report  (figure  3-13)  lists  each  procedure  and  the 
standards  It  violates.  First,  the  name  of  the  proceduie,  description, 
version  Information,  and  page  number  are  extracted  from  the  master  file 
and  printed.  Then  the  software  quality  metrics  for  the  procedure  are 
compared  against  the  software  standards  and  the  violations  are  listed. 
The  first  column  of  the  list  of  violations  contains  the  description  of 
the  standard.  The  next  column  contains  the  value  provided  (or 
calculated)  for  the  software  being  analyzed.  The  next  column  has  the 
"permitted  range,"  which  is  the  range  of  values  which  the  value  pro¬ 
vided  for  the  software  must  fall  within  to  meet  the  standard.  Finally, 
there  is  a  reference  to  the  document  containing  the  standard  (where  ap¬ 
plicable). 

b.  The  SOFTPRO  summary  report  (figure  3-14)  summarizes  the  violations  of 
the  standards.  The  first  column  contains  the  description  of  the 
standard.  The  next  column  contains  the  number  and  percentage  of 
procedures  which  met  each  standard.  The  next  column  contains  the  number 
and  percent  of  procedures  which  violated  each  standard.  The  last  column 
provides  a  reference  to  the  document  containing  the  standard.  Ad- 
aitionally,  the  quality  values  are  summarized  for  all  the  modules  and 
listed  individually  for  each  module  (see  figure  3-15). 

3.4.3  SYSTRUCT  Report.  The  SYSTRUCT  report  (figure  3-17)  shows  differences  in 
subroutine  calls,  variable  usage,  and  software  quality  metrics  between  two 
versions  of  the  software  under  analysis.  First,  the  name,  description,  and  page 
number  of  old  and  new  versions  are  p~  ited.  If  the  option  for  new  structure  is 
set,  a  structure  chart  similar  to  the  STAMP  structure  chart  is  printed  for  the 
structure  of  the  new  version  of  the  procedure.  Next  a  header  is  printed;  this 
centres  the  version  information  for  the  old  and  new  versions.  If  changes  in 
subroutine  calls  are  made,  the  subroutines  called  which  are  comnon  to  both 
versions  are  listed;  then  the  subroutine  calls  which  have  been  added  or  deleted 
are  reported.  Next,  the  software  metrics  for  which  values  have  changed  are  re¬ 
ported.  There  is  also  a  flag  with  each  metric  to  associate  it  with  either  a 
change  in  executable  code  or  a  change  in  program  documentation.  A  change  in  ex¬ 
ecutable  code  supersedes  a  change  in  program  documentation.  The  probable  type 
of  change  or  "no  change"  is  flagged  upon  completion  of  each  procedure. 

3.4.4  PATCHANA  Report.  The  PATCHANA  report  (figure  3-19)  lists  the  structure 
of  two  versions  of  a  procedure  s^de  by  side  and  shows  where  differences  are. 
First  the  name  and  description  of  the  procedure  are  given.  Then  a  header  con¬ 
taining  the  version  information  for  the  old  and  new  versions  of  the  procedure  is 
printed.  The  rest  of  the  report  is  in  three  sections:  the  change  indicator, 
the  old  version,  and  the  new  version.  The  change  indicator  can  flag  either  a 
structural  change  or  a  change  in  attributes  for  the  particular  path.  A 
structural  change  is  flagged  by  a  "P"  for  path  or  an  "N"  for  node,  where  the 
change  is  a  change  in  the  execution  path  due  to  branches  being  added  or  deleted. 
A  change  in  attributes  for  a  particular  path  is  a  change  in  the  subroutines 
called,  variables  used,  or  one  or  more  of  the  quantifers  changed.  These  changes 
are  flagged  by  "S",  "V",  or  "Q"  followed  by  the  quantifier  numbers.  The  old  and 
new  version  sections  have  the  same  format— the  path  number,  and  path  segment 
description  followed  by  the  values  of  the  three  quantifiers.  If  subroutines  are 
called,  they  are  listed  on  the  next  line. 
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TERMS  AND  ABBREVIATIONS 


COMPRO 

DEC 

DECUS 

Encoder 

External  procedures 
H  IPO 

HIPO  chart 

MACRO  SPIT BOL 
Master  file 

Module 
Node 
PATCH ANA 
Path 

PFA 

PFALIB 

Program  structure 

Quantifiers 

RAT  FOR/RAT  FI  V 
SOFT PRO 

Software  patch 
Software  system 


Comment  Processor. 

Digital  Equipment  Corporation. 

DEC  User  Society. 

A  program  which  reads  the  source  code  for  the  system 
being  analyzed  and  creates  a  master  file  for  use  by 
other  PFA  programs. 

Procedures  which  exist  outside  of  the  software  being 
analyzed,  e.g.,  operating  system  utilities. 

Hierarchy  plus  Inputs,  Processing,  and  Outputs. 

A  chart  relating  inputs  and  outputs  to  the  processing 
algorithm  which  uses  or  creates  them. 

A  SN0B0L4  compatible  interpreter  f-~r  the  VAX. 

The  file  which  contains  a  representation  of  the 
attributes  of  the  software  being  analyzed. 

A  separately  compilable  procedure  or  subroutine. 

A  point  of  decision  in  execution  path  selection. 

Patch  Analysis  Program. 

A  segment  of  instructions  which  does  not  contain  any 
branches. 

Program  Flow  Analyzer. 

PFA  Library. 

Graph  of  the  sequence  of  all  possible  paths  which  may  be 
executed  within  a  program. 

A  value  which  quantifies  or  totals  some  attribute  on  a 
path. 

A  structured  FORTRAN  translator. 

Software  Profile  Program. 

A  change  in  source  code. 

Consists  of  one  or  more  computer  programs  which  perform 
one  or  more  related  functions. 
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TERMS  AND  ABBREBIATIONS  (Cont'd.) 


STAMP  Structure,  Timing,  Analysis,  Modeling  Program. 

Standards  file  File  which  contains  user-entered  standards  in  a 

prescribed  format. 

Structure  chart  Shows  a  subroutine  call  hierarchy  in  the  form  of  a  tree 

graph. 

SYSTR'dCT  System  Structure  Comparison  Program. 

TECOM  Test  and  Evaluation  Command. 

U.S.  Army  Electronic  Proving  Ground. 
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Figure  B-3.  Listing  and  Version  Definition 
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Figure  B-4.  Prologue  Comments 
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Figure  B-5.  Path  Definition 
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Figure  B-6.  Subroutine  Calls  Information 
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Figure  B-7.  Variable  Information 
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SECTION  1,  GENERAL  DESCRIPTION 


1.1  Purpose  of  the  Program  Maintenance  Manual.  The  objective  of  this  Program 
Maintenance  Manual  for  the  Program  Flow  Analyzer  (PFA)  system,  TtCQM  Project 
Number  7-C0-RD0-EP1-004 ,  is  to  provide  the  maintenance  programmer  presonnel 
with  the  information  necessary  to  effectively  maintain  the  system. 

1.2  Project  References.  PFA  is  a  software  analysis  system.  It  consists  of 
various  programs  which  identify  software  quality,  program  structure,  and 
program  features  which  aid  or  interfere  with  program  maintainability. 

PFA  is  sponsored  by  the  U.S.  Army  Electronic  Proving  Ground  ( USAEPG)  at 
Fort  Huachuca. 

The  following  are  PFA  documents  of  interest  to  the  maintainer. 

USAEPG,  Program  Flow  Analyzer  Users  Manual,  30  November  1982,  UNCLAS¬ 
SIFIED 


USAEPG,  Program  Flow  Analyzer  Plan,  30  October  1982,  UNCLASSIFIED 

USAEPG,  Methodology  Investigation  Proposal — Program  Flow  Analyzer, 
March  1979,  UNCLASSIFIED - - -  - - 1 - 

USAEPG,  Program  Flow  Analyzer  A-Level  Specification,  4  April  1980, 
UNCLASSIFIED. 


1.3  Terms  and  Abbreviations.  Terms,  definitions,  abbreviations,  and  acronyms 
are  included  in  appendix  A. 


SECTION  2.  SYSTEM  DESCRIPTION 


2.1  System  Appl ication.  PFA  is  a  software  tool  used  for  automating  the  an¬ 
alysis  of  a  software  system  to  identify  software  quality,  program  structure, 
and  program  maintainability.  PFA  performs  the  following  functions: 

a.  Software  documentation  aid 

b.  Program  structure  analysis  on  the  system  level 

c.  Program  structure  analysis  on  the  module  level 

d.  Software  quality  analysis 

e.  Analysis  of  system  configuration  changes 

f.  Software  modification  analysis  on  the  module  level 

PFA  can  automate  review  of  design-level  specifications  and  code,  software 
quality  metrics,  and  comparison  of  different  versions  of  software  which  are 
normally  performed  manually.  PFA  generates  reports  that  can  be  compared  to 
design  specifications;  this  reduces  effort  needed  to  trace  from  code  to  design 
specifications.  PFA  computes  and  compares  software  quality  metrics  to  user- 
selected  software  quality  standards,  thereby  automating  the  software  quality 
assessment.  PFA  compares  two  versions  of  software,  first  an  overall  com¬ 
parison  and  then  a  comparison  of  selected  modules,  and  generates  reports  which 
identify  changes. 

2.2  Security  and  Privacy.  The  PFA  system  is  unclassified  and  is  currently 
set  up  to  identify  all  output  as  unclassified. 

2.3  General  Description.  The  structure  of  the  PFA  system  is  presented  in 
figure  2-1. 

2.4  Program  Description.  The  following  paragraphs  provide  a  description  of 
the  PFA  programs:  At/TOxxxx,  COMPRO ,  STAMP,  SOFTPRO,  SYSTRUCT,  PATCHANA,  and 
PFALIB.  The  encoder  program  (AUTOxxxx)  is  specific  to  the  language/machine 
combination  being  analyzed.  Only  details  applicable  to  encoders  in  general 
are  provided  here.  The  remaining  PFA  programs  are  generic  in  nature.  HIPO 
and  structure  charts  for  these  programs  are  included  in  Volume  II,  Appendix  B 
and  C.  PFA  programs  are  written  in  MACROSPITBOL  with  the  exceDtion  of 
SOFTPRO,  written  In  VAX  FORTRAN. 

2.4.1  Encoder  (AUTOxxxx).  The  encoder  is  a  front-end  program  to  the  PFA  sys- 
tem,  which  translates  computer/software/language-specific  programs  into  a  re¬ 
presentation  which  is  stored  in  a  data  base  called  the  master  file.  This 
master  file  is  then  read  by  other  PFA  programs  that  generate  reports.  The  en¬ 
coder  Is  customized  for  each  application  to  accommodate  the  specific 
machine/language  combination  of  the  software  being  analyzed. 

2.4.2  Comment  Processor  (COMPRO).  COMPRO  extracts  and  processes  comments  for 
creating  documentation.  cOmprO  reads  program  source  code  files  that  contain 
comments  In  a  specific  format.  The  information  contained  in  these  comments  is 
used  to  create  a  master  file  tnat  can  be  processed  by  other  PFA  programs  to 
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generate  reports  used  for  program  documentation.  PFA  programs  are  commented 
In  tnis  manner  to  provide  automated  HIPO  and  structure  charts  for  the  PFA  sys¬ 
tem  . 


Figure  2-1.  Structure  of  the  PFA  System 
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2.4.3  Structure,  Timing,  Analysis,  Modeling  Program  (STAMP).  STAMP  provides 
the  program  structure  analysis  function.  The  STAMP  program  reads  the  master 
file  and  generates  overall  reports  on  the  system  under  analysis  to  aid  in  mod¬ 
eling  that  system  and  to  provide  information  about  the  structure  of  that  sys¬ 
tem.  STAMP  provides  five  reports,  as  follows: 

a.  The  external  procedures  report  lists  each  module  which  calls  sub¬ 
routines  outside  the  set  of  modules  being  analyzed  and  the  namt  of  the  sub¬ 
routines  called. 

b.  The  structure  chart  shows  the  module  call  hierarchy  of  the  system  and 
flags  external  and  recu-sive  subroutines. 

c.  The  function  list  provides  a  list  of  all  task-level  modules  in  the 
system,  with  the  name  of  the  module,  a  brief  description,  and  version  informa¬ 
tion. 

d.  The  module  list  contains  a  directory  of  the  modules  being  c'Mlyzed, 
arranged  in  alphabetical  order.  It  also  contains  an  indicator  to  signal 
whether  the  module  is  task  level,  subroutine  level,  or  an  unused  entry  point; 
the  top  and  bottom  hierarchical  level  on  which  the  module  is  called;  a  brief 
module  description;  the  version  information;  and  the  page  number  of  the 
source  listing  where  the  module  is  located. 

e.  The  HIPO  chart  lists  the  name  of  the  module,  a  brief  module  de¬ 
scription,  the  version  information,  the  page  number  of  the  source  listing  pro¬ 
logue  comments,  and  the  variables  input  and  output.  The  processing  de¬ 
scription  in  the  HIPO  chart  includes  the  path  segment  structure  of  the  module. 
Each  path  segment  contains  the  names  of  modules  called,  comments  about  the 
path,  three  quantifiers  (discussed  below)  and  the  sequence  number  range  of  the 
source  statements  which  make  up  the  path  segment. 

The  quantifiers  are  user-selected  values  (determined  by  the  particular  en¬ 
coder  used)  extracted  from  the  software  being  analyzed.  Examples  are  ex¬ 
ecution  module  timing,  source  statement  counts,  and  machine  instruction 
counts.  Those  items  which  are  not  available  do  not  prohibit  processing.  The 
STAMP  program  will  report  on  the  information  available. 

2.4.4  Software  Profile  Program  (ST  FT  PRO) .  SOFTPRO  provides  the  software 
quality  analysis  function.  SOFT  PRO  reads  the  master  file  and  a  software 
standards  file  and  generates  two  reports,  as  follows: 

a.  The  software  profile  reports  for  each  module  list  the  violations  of 
software  standards  as  defined  by  the  user  in  the  software  standards  file.  The 
violations  state  the  standard,  the  value  for  the  software  oeing  analyzed,  the 
permitted  range  of  values,  and  the  reference  to  the  regulation  from  which  the 
standard  is  derived. 

b.  The  profile  summary  contains  the  list  of  standards,  the  number  and 
percent  of  modules  meeting  each  standard,  the  number  and  percent  of  modules 
violating  each  standard,  and  the  reference  to  the  regulations  containing  each 
standard.  Additionally,  quality  values  are  summarized  for  all  modules  and 
listed  individually  for  each  module. 
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2.4.5  System  Structure  Comparator  (SYSTRUCT).  SYSTRUCT  provides  analysis  of 
system  configuration  changes.  SYSTRUCT  reads  two  master  files  representing 
different  versions  of  the  software  system  under  analysis.  The  SYSTRUCT  report 
lists  changes  in  variables  used  by  each  module,  changes  in  software  quality 
parameters  {the  ones  reported  by  SOFTPRO),  and  modules  which  have  been  added 
to  or  deleted  from  the  current  version  of  the  software  being  analyzed.  The 
changes  are  of  two  types:  those  affecting  executable  code  and  those  affecting 
code  documentation.  When  changes  affect  executable  code,  a  list  of  the  mod¬ 
ules  changed  (selection  file)  is  generated  for  use  by  the  patch  analysis 
program. 

2.4.6  Patch  Analysis  Program  (PATCHANA).  PATCHANA  provides  a  software  patch 
(source  code  change)  analysis  function.  PATCHANA  reads  two  master  files  or 
subsets  of  master  files  representing  two  versions  of  the  software  being  an¬ 
alyzed.  A  selection  file  which  contains  a  list  of  modules  to  be  compared  is 
also  read.  Selection  can  be  made  interactively  or  via  the  selection  file 
created  by  SYSTRUCT.  The  report  lists  the  path  segment  structure  for  both 
versions  and  indicates  (with  codes  and  arrows)  the  location  of  differences  and 
the  type  of  change  for  each  version.  When  structural  differences  occur,  the 
differences  are  flagged  from  their  start  either  through  the  remainder  of  the 
module  or  to  the  point  where  the  structures  of  the  two  versions  are  congruent. 
PATCHANA  finds  differences  in  structure,  subroutine  calls,  use  of  variables, 
and  the  three  quantifiers. 

2.4.7  PFA  Library  Routines  (PFALIB).  The  PFA  library  routines  are 
MACROSPlt&)L  routines  that  are  used  by  the  various  PFA  programs.  The  following 
routines  constitute  PFALIB: 

CENTER  returns  a  given  string  centered  within  a  string  of  given  length. 

CLS  clears  the  terminal  (user's)  screen. 

OECR  decrements  the  argument  by  one. 

DTOO  is  used  to  convert  decimal  numbers  into  octal  numbers. 

ENDOUT  prints  the  'UNCLASSIFIED'  caveat  on  the  last  page. 

ENTER  returns  the  next  available  channel  number. 

FIELD1  extracts  a  string  of  characters  of  a  given  length  from  a  larger 

string  of  characters,  starting  at  a  given  character  position.  It  also 

trims  leading  and  trailing  blanks  from  the  string  it  returns. 

INCR  Increments  the  argument  by  one. 

INIOUT  performs  initialization  for  OUTOUT. 

ITMCMP  determines  if  an  Item  Is  in  a  list. 

LIST  returns  an  Item  at  a  specified  index.  If  the  given  index  Is  greater 

than  the  Index  of  the  last  Item  In  the  list,  the  last  Item  is  returned. 

LSTADD  adds  a  given  item  to  the  end  of  the  list. 
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LSTOLN  deletes  an  item  at  a  given  Index  from  a  list. 

LSTDLS  deletes  all  occurrences  of  a  <  Iven  item  from  a  list. 

LSTFND  returns  the  index  of  a  given  item  in  a  list. 

LSTGET  returns  the  item  at  a  given  index  from  a  list. 

LSTINN  inserts  an  item  at  a  given  index  in  a  list. 

LSTINS  inserts  an  Item  before  another  given  item  in  a  list. 

LSTLEN  returns  the  number  of  items  in  a  list. 

MAX  returns  the  maximum  of  two  real  or  integer  numbers. 

MIN  returns  the  minimum  of  two  real  or  integer  numbers. 

NODUP  deletes  duplicate  entries  from  a  list. 

0CT8IN  returns  a  binary  representation  (ones  and  zeros)  of  a  given  octal 
number. 

OTOD  returns  a  decimal  representation  of  a  given  octal  number. 

OUTOUT  outputs  a  given  line  and  provides  the  'UNCLASSIFIED'  caveat,  page 
numbering,  and  header  at  page  breaks. 

PAD  returns  a  string  of  blanks  of  given  length. 

PRETRM  trims  leading  blanks  from  a  given  string. 

REWIND  rewinds  a  file  on  a  given  channel  and  releases  variables  tied  to 
that  channel . 

ROUND  returns  a  given  real  number  rounded  to  two  decimal  places.  It  does 
not  affect  integer  numbers. 

STROUT  takes  as  many  as  the  given  number  of  characters,  as  delimited  by  a 
comma,  from  a  given  string  and  places  them  on  the  returned  string.  The 
Input  string  is  shortened  by  the  number  of  characters  in  the  returned 
string. 

SWAP  swaps  the  contents  of  two  variables. 


SECTION  3.  ENVIRONMENT 


3.1  Equipment  Environment.  PFA  is  currently  Implemented  on  a  DEC  VAX/VMS, 
mode"!  11/780.  PFA  software  is  resident  on  disk;  software  to  be  analyzed  is 
input  via  nine-track  tape  drives. 

3.2  Support  Software.  PFA  currently  requires  the  following  DEC  software: 

a.  VMS,  Version  3.0  or  later 

b.  VAX  FORTRAN 

The  following  software  from  other  sources  is  also  required: 

MACROSPITBOL ,  available  from  DEWAR  Information  Systems,  Inc.,  221  West 
Lake  Street,  Oak  Park,  IL  60302 

3.3  Data  Base.  PFA  uses  two  data  files,  the  master  file  and  the  standards 
Hie.  The  master  file  contains  condensed/ summary  information  on  the  program 
to  be  analyzed.  It  Is  used  by  STAMP,  SOFTPFD,  SYSTRUCT,  and  PATCHANA  to  an¬ 
alyze  and  report  on  program  structure,  maintainability,  and  software  duality. 
The  master  file  may  be  edited  by  using  the  system  editor. 

The  standards  file  contains  information  on  software  standards.  It  is  used 
by  SOFTPRO  to  calculate  and  report  standards  violations  and  by  SYSTRUCT  to 
identify  software  quality  measures  which  have  changed  between  two  versions  of 
the  software  being  analyzed. 

3.3.1  General  Characteristics.  The  following  are  the  general  characteristics 
of  the  data  base  files: 

3. 3.1.1  Master  File.  The  master  file  is  created  by  system-specific  encoders 
(AUTOxxxx  and  CGMPRO).  The  master  file  filename  is  specified  by  the  user  at 
run  time.  The  user  may  specify  any  filename  acceptable  to  the  system,  but,  by 
convention,  the  file  extension  is  MST.  The  master  file,  or  a  subset.  Is  used 
by  STAMP,  SOFTPRO,  SYSTRUCT,  and  PATCHANA  to  analyze  and  report  on  program 
structure,  maintainability,  and  software  quality.  Additionally,  the  master 
file  may  be  edited.  The  master  file  is  read-only  to  all  programs  except  the 
editor,  AUTOxxxx,  and  C0MPR0.  The  master  file  is  an  ASCII  sequential  file  re¬ 
sident  on  disk  storage.  Records  are  fixed  format,  delimited  by  a  carriage  re¬ 
turn/1  inefeed  sequence,  with  a  data  length  of  72  characters.  The  amount  of 
storage  required  varies  with  the  application. 

3. 3. 1.2  Standards  File.  The  standards  file-is  created  In  two  parts.  First, 
the  developer  of  the  encoder  creates  a  file  containing  descriptions  of  the 
basic  standards,  for  which  values  are  output  by  the  encoder.  Then,  before  run 
time,  the  user  adds  descriptions  of  standards  which  are  user  defined  in  terms 
of  the  basic  standards.  The  standards  file  filename  is  specified  by  the  user 
at  run  time.  The  user  may  specify  any  name  acceptable  to  the  system  but,  by 
convention,  the  file  extension  Is  STD.  The  standards  file  is  used  by  SOFTPRO 
to  calculate  and  report  standards  violations  and  by  SYSTRUCT  to  identify 
software  quality  measures  which  have  changed  between  two  versions  of  the 
program  being  analyzed.  The  standards  file  is  read-only  to  all  PFA  programs. 
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The  standards  file  is  a  free  format,  ASCII,  sequential  file  maintained  on  disk 
storage.  The  amount  of  storage  required  varies  with  the  application. 

3.3.2  Organization  and  Detailed  Description.  The  following  is  a  detailed  de¬ 
scription  of  the  dataoase  files. 

3. 3. 2.1  Master  File. 


a.  Layout.  Figures  3-1  through  3-10  show  the  layout  of  the  master  file. 
Currently  there  are  eleven  record  types  in  the  files  (a  header  type  and  ten 
data  types).  The  eleven  record  types  contain  the  following  information: 

Type  Information 

Header  Record 

0  Library  Routine  Definition 

1  Task  or  Subroutine  Definition  ' 

2  Listing  and  Version  Information 

3  Prologue  Comments 

4  Path  Definition 

5  Subroutine  Calls  Information 

6  Variable  Information 

7  In-Line  Cumments 

8  Software  Quality  Information 

9  Entry  Point  Definition 

b.  Groupings  and  Order.  Within  the  master  file,  all  the  records  for  a 
module  are  grouped  together.  Within  each  module  group,  the  records  have  the 
following  order: 

(1)  A  header  record  of  the  form:  "#-H-  modname",  left-justified. 

(2)  A  type  0  or  1  record,  as  appropriate. 

(3)  A  type  2  record  and,  optionally,  type  3  records.  The  type  2  re¬ 
cord  may  appear  anywhere  within  this  group. 

(4)  The  path  Information  records  are  grouped  together  by  path  and 
Include  type  4,  5,  6  and  7  records.  Each  group  defines  a  path.  The  de¬ 
finition  of  a  path  includes  the  specification  of  a  from  node,  or  start  point, 
for  the  path.  The  groups  are  ordered  so  that  the  from  nodes  specified  by  the 
groups  appear  in  the  master  file  In  the  same  order  as  the  from  nodes  appear  In 
the  program  llstlny.  The  records  within  the  path  groups  are  ordered  as  fol¬ 
lows:  The  optional  type  4  record  must  appear  first,  followed  by  optional  type 
5,  6  and  7  records,  which  may  be  intermixed. 
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(5)  Optional  type  8  records,  in  order. 

(6)  Optional  type  9  records  which  may  be  intermixed  with  type  8  rec¬ 
ords  and/or  path  groups. 

c.  Fields.  See  Figure  3-1  through  3-10  for  the  layout  of  the  fields  de¬ 
scribed  in  Table  3-1. 

3. 3. 2. 2  Standards  File. 


The  software  standards  file  is  used  for  comparing  the  software  being  an¬ 
alyzed  to  specific  standards. 

a.  Layout.  Each  record  in  the  standards  file  contains  eight  fields,  each 
terminated  by  a  semicolon. 

b.  Groupings  and  Order.  The  records  in  the  standards  file  may  be  in  any 
order. 


c.  Fields.  A  sample  standards  file  is  presented  in  figure  3-11.  The 
fields  are  defined  as  follows: 

(1)  Identifier.  The  Identifier  has  two  ranges: 

(a)  1  to  14,  basic  standard  taken  directly  from  the  cor¬ 
responding  field  on  the  master  file  type  8  record. 

(b)  Any  other  value. 

Range  (a)  specifies  which  item  of  the  software  quality  record  the  standard  re¬ 
cord  describes.  Range  (b)  provides  scratch  records  for  calculations  or  con¬ 
tains  identification  and  calculations  for  derived  or  calculated  software  metr¬ 
ics. 


(2)  String  description.  This  Is  a  brief  description  of  the  standard 
(maximum  of  40  characters)  stated  as  the  requirement  needed  (value)  to 
meet/pass  the  standard,  for  example:  McCabe's  complexity  <  10  (meets 
standard) 


(3)  Weighting  factor.  This  is  an  Integer,  zero  or  greater,  which 
gives  a  relative  weight  to  each  standard.  Zero  means  the  record  is  for 
calculation  only  and  is  not  reported.  Numbers  greater  than  zero  rate  the  re¬ 
lative  severity  of  violating  the  standard;  the  greater  the  number,  the  more 
severe  the  consequences  of  the  violation. 

(4)  Lowest  permitted  value.  If  the  value  supplied  (or  calculated) 
for  the  standard  record  is  less  than  the  lowest  permitted  value,  the  standard 
is  violated. 

(5)  Highest  permitted  value.  If  the  value  supplied  (or  calculated) 
for  the  standard  record  is  greater  than  the  highest  permitted  value,  the 
standard  is  violated. 

(6)  Value  or  calculation.  If  the  identifier  is  in  the  range  (a) 
above,  then  this  field  is  left  blank;  otherwise,  the  field  contains  an  expres- 


sion  used  for  calculations.  The  expression  must  be  in  reverse  Polish  notation 
with  a  comma  following  each  term  of  the  expression.  Terms  which  are  enclosed 
in  parentheses  are  identifiers  which  are  replaced  by  a  value  or  calculation 
from  the  standard  record  indicated  by  that  identifier.  Terms  which  are 
numbers  are  used  as  constants  in  the  calculations.  The  four  arithmetic  oper¬ 
ators  permitted  are  +,  *,  /. 

(7)  Code/documentat  on  indicator.  This  indicator  is  "CH  if  the 
standard  affects  source  code  specific  to  a  programming  language  or  “0"  if  the 
standard  affects  program  documentation  contained  in  comments. 

(8)  Standard  reference.  This  field  refers  to  the  document  where  the 
standard  is  found. 

See  figure  3-12  for  the  layout  of  the  fields  described  in  Table  3-1 I.  The 
sizes  of  all  fields  are  variable.  Null  fields  are  indicated  by  two  con¬ 
secutive  semicolons. 

d.  Provisions  for  Expansion.  There  are  provisions  for  14  basic  standards 
with  up  to  30  total. 
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Figure  3-7.  Variable  Information 
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Figure  3-11.  Software  Standards  File 
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Figure  3-12.  Software  Standards  File  Records 
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SECTION  4.  PROGRAM  MAINTENANCE  PROCEDURES 


4.1  Conventions. 

4.1.1  Naming  Conventions.  The  following  conventions  were  used  for  the  as¬ 
signment  of  mnemonics. 

a.  Counters  usually  begin  with  MN"  or  contain  “NUM" . 

b.  The  mnemonics  MRL“  and  "RP"  are  used  for  report  file  line  and  page 
count,  respectively. 

c.  The  variable  "TRUE"  Is  set  to  1;  "FALSE"  is  set  to  0. 

d.  Mnemonics  which  specify  input/output  channel  numbers  end  with  "CHNL" 
or  "CHNNL" . 

e.  Mnemonics  which  have  to  do  with  batch  processing  mode  start  with 
"BAT". 

f.  Variables  used  in  the  report  file  interface  may  contain  "REP". 

g.  Variables  and  subroutine  names  containing  "STD"  are  used  in  processing 
standards  records. 

h.  Variables  and  subroutine  names  containing  "MOD"  are  used  in  module 
processing. 

1.  Variables  and  subroutine  names  containing  "OUT"  are  used  in  output 
processing. 

j.  Variables  and  subroutine  names  containing  "MST"  are  used  in  master 
file  processing  or  to  indicate  that  data  come  from  a  master  file. 

k.  Variables  and  subroutine  names  containing  “STK"  or  "STAK"  are  used  for 
stacks. 

l.  Variables  and  subroutine  names  containing  "NEW"  refer  to  a  new  ver¬ 
sion. 

m.  Variables  and  subroutine  names  containing  "OLD"  refer  to  an  old  ver¬ 
sion. 

n.  Variables  containing  "TTY"  (e.g.,  TTY,  TTYIN,  TTYNOCR)  refer  to  user 
terminal . 

o.  Variables  containing  "ARND"  or  "EXT"  are  exit  points  for  local  control 
structures. 

4.1.2.  Commenting  Conventions.  Figure  4-1  is  an  example  of  the  conventions 
used  in  PFA  source.  In  general ,  all  comments  and  code  for  a  module  must  be 
grouped  together  within  the  source  file.  A  description  of  the  conventions 
used  within  a  module  follows: 
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SVIiFnVT  INE  READS  TD  -  READ  STANDARDS  FILE 
PURPOSE 

RFAOSTD  READS  THE  STANDARDS  FILE  AND  STORES  THE  INFORMATION  FOR 
THE  BASIC  STANDARDS  IN  Tt-E  STANDARDS  TABLE. 

CAL  L  PEADSTD  <  > 

VARIABLE  LIST 

CCSC  -  STANDARD  DESCRIPTION 

CIV  -  EXPRESSION  FOR  CALCULATING  STANDARD 

(DX  ••  STANDARD  LABEL  AND  INDEX  INTO  STANDARDS  TABLE 

MAXV  -  MAXIMUM  VALUE  TO  MEET  STANDARD 

MI NV  -  MINIMUM  VALUE  TO  MEED  STANDARD 

ST  GN  IF  -  FLAG  INDICATING  WHETHER  A  CHANCE  IN  THE  VALUE  OF 
THIS  STANDARD  SIGNIFIES  A  CODE  OR  C  OCUMCNT  ATI  ON 
CHANCE  IN  THE  MODULE  (»C.  D) 

STANDARD  -  INPUT  VARIABLE  FOR  STANDARDS  FILE 
STD  -  SEE  STD  DATA  STRUCTURE 

ST DP EC  -  STANDARD  TABLE  ENTRY 

SID  TAB  -  STANDARDS'  TABLE 

TEMP  -  INPUT  RECORD  FROM  STANDARDS  FILE 

UGT  -  FLAC  INDICATING  WHETHER  CURRENT  STANDARD  IS  TO  BE 

REPORTED 

»0  -  DO  NOT  REPORT 

>0  -  DO  REPORT 

FILES  USED 

STANDARDS  FILE  -  FILE  SPECIFYING  PROGRAM  STANDARDS 
CALLS  LIST 


RC.NO  RECORD  AND  GATHER  DATA  \1-1.E 


INRUT  STANDARD  IP.  TEMP  ST.  DESC.  ST.  WCT:  ST.  MINV:  ST,  MAXV:  ST. 

G1V  ST. 3ICNIF  ST,  IDX  :  ST.  STDREC:  STD 
OUTPUT  N  IN.  TEMP  ST  .  IDX  :  ST ,  DESC  :  ST,  WCT  ST,  M  INV  ST.  M  AXV:  ST,  0  IV:  ST. 

SIGNIF  ST, STDREC:  STQ.  IDX;  IN.  STDT ABC1  DX> :  STD.  3TDTAB:  TA 
CALLS  LIST 


PEADSTD  N  -  0 

STDTAD  »  TABLE <171 

f 

P3I  TEMP  -  S^ANDRP  F  ( RETURN) 

IOX  -  LIST (TEMP. 2.  MM 
DESC  -  LIST  (TEMP.  2.  M  M 
W<3T  -  LIST  (TEMP.  3.  MM 
MINV  »  LIST(TEMP.  4.  M  M 
MAXV  »  L I  ST  ( TEMP.  3,  M  M 
a  IV  -  LIST ( TEMP  A.  M  ' ) 

SlCNfF  «  LIST( TEMP.  7.  *  i  M 

STDREC  -  STD( DESC.  WCT,  MINV, MAXV, OIV.  NULL.  SICNIF) 


►  TEST  FOR  BASIC  STANOARD  STORE  INFORMATION  FOR  RASIC  STANDARDS 
*  IN  STANDARDS  table.  SKIP  USER-DEFINED  standards. 

IDX  -  CONVERT (IDX,  '  INTEGER  * )  P(RS1) 

STDTAOMDX;:  -  STDREC  :(RSI> 


Figure  4-1.  A  Sample  PFA-Commented  Source  Program 
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a.  Prologues 


(1)  Each  module  has  a  prologue. 

(2)  The  prologue  is  delimited  by  asterisks.  This  means  that  the 
prologue  must  be  preceded  and  followed  by  a  line  consisting  only  of  a  string 
of  asterisks  and  that  each  line  in  the  prologue  must  begin  and  end  with  an 
asterisk. 


(3)  Every  prologue  contains  as  the  first  non-blank  line: 

TASK 

SUBROUTINE  :  <name>  -  <description> 

LIBRARY  ROUTINE 

where,  if  the  module  has  multiple  entry  points,  name  is  the  name 
of  the  first  entry  point. 

(4)  Following  item  3  is  the  module  description: 

AUTHOR: 

DATE  STARTED: 

DATE  LAST  MODIFIED: 

PURPOSE:  <function  of  module> 

DESCRIPTION:  <general  design  description> 

CALL: 

PARAMETER  LIST:  <parameters  and  descriptions> 

USER-DEFINED  DATA  STRUCTURES:  <structures.  fields  and  de¬ 
scriptions:* 

VARIABLE  LIST:  <var1ables  and  descriptions> 

FILES  USED:  < T i  1  e  names  and  descriptions:* 

CALLS: 

LIMITATIONS: 

ERRORS: 

as  there  are  appropriate  data  to  Include. 

(5)  For  each  additional  entry  point  the  module  contains,  (4)  above 
is  followed  by: 
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ENTRY  POINT:  <name>  -  <description> 
and  again,  as  many  of  the  items  in  (4)  above  as  appropriate, 
b.  In-Line  Comments 

(1)  All  in-line  comments  begin  with  an  asterisk  and  are  separated 
from  code  by  strings  of  asterisks. 

(2)  In-line  comments  do  not  contain  1  '. 

(3)  The  in-line  comments  may  contain  pseudo  path  segment 
specifications.  These  specifications  document  the  flow  of  control  in  a  module 
and  are  used  by  COMPRO,  the  comment  processor,  and  STAMP  to  create  HIPO 
charts.  If  used,  the  path  segment  specifications  have  the  following  format 
and  meaning: 


(a)  The  specification  for  a  path  segment  begins  on  the  first 
comment  to  be  included  in  the  segment. 

(b!  The  specification  is  the  rightmost  item  on  the  comment 
line. 

(c)  The  specification  is  of  the  form: 

[m-][nl,n2,...][E] 

where  m  is  the  optional  node  label  for  the  start  of  the  path 
segment,  ni  are  the  optional  node  labels  to  which  the  segment  branches,  and  E 
indicates  branch  to  exit.  If  the  from  node  label  is  null,  the  from  node  label 
will  be  assumed  to  be  the  current  node  count  for  this  module.  If  the  to  node 
labels  (including  E)  are  null,  the  to  node  label  will  be  assumed  to  be  the 
current  node  count  for  this  module  "plus  one.  If  this  path  segment  is  an  entry 
point  for  the  module  but  is  not  the  first  entry  point  to  the  module,  m  must  be 
the  name  of  the  entry  point. 

(d)  The  last  path  specification  in  a  module  has  a  t£  node 

specified. 

(4)  All  referenced  and  modified  variables  appearing  in  a  pseudo  path 
segment  are  listed  in  comments  within  the  path  segment  for  use  by  COMPRO  and 
STAMP.  If  there  is  no  path  segment  specification,  all  referenced  and  modified 
variables  for  the  module  are  listed.  Comments  listing  referenced  or  modified 
variables  have  the  respective  formats: 

INPUT :  varl[:type],var2[:type},...vari[:type]. 


...varn[ :type] 


OUTPUT :  varl[:type],var2[:type],...varl£:type]. 


Several  lists  may  be  included  in  one  path  segment. 

(5)  All  subroutines  called  in  a  pseudo  path  segment  are  listed  in 
comments  within  the  path  segment  for  use  by  COMPRO  and  STAMP.  If  there  is  no 
path  segment  specification,  all  subroutines  called  in  the  module  are  listed. 
Comments  listing  the  calls  have  the  format: 

CALLS:  calll,  cal  12 . . .cal  11, 
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...calln 

Several  lists  may  be  included  in  one  path  segment. 

4.2  Verification  Procedures.  Large  master  files  should  be  used  to  test  the 
performance  of  the  PFA  programs.  Master  files  should  contain  all  possible 
inputs  which  affect  the  PFA  program  being  tested.  Master  files  for  testing 
can  be  generated  by  running  an  encoder  on  a  representative  sample  of  software. 
The  resulting  master  file  can  then  be  edited  to  add  the  necessary  features  for 
the  test. 

4.3  Error  Conditions. 


4.3.1  COMPRO.  COMPRO  indicates  the  following  errors: 

a.  Massage:  "ERR  10:  ERROR  PROCESSING  LINE  IN  MODULE  _ " 

"<1ine>" 

This  means  that  COMPRO  has  found  a  line  in  the  PFA  source  with  an  un¬ 
expected  format.  The  message  indicates  an  error  within  COMPRO,  and 
processing  terminates. 

b.  Message:  "ERR20:  UNEXPECTED  END  OF  FILE  IN  MODULE _ M 

This  leans  that  COMPRO  has  found  ^n  end  of  file  while  reading  a  multi- 
line  list.  The  message  indicates  an  error  in  the  PFA  sourcp.  Process¬ 
ing  terminates. 

4.3.2  STAMP  AND  PAT CHAN A.  These  programs  display  the  following: 

Message:  "BAD  MAP  FOR _ “ 

This  means  that  there  is  a  to  label  without  a  corresponding  from  label  or 
that  the  from  or  to  label  is  null  for  a  path  datum  in  the  master  file. 

This  results  fronfTncomplete  path  structure  generated  by  the  encoder  or 
from  dead  code  in  the  source  code  being  analyzed. 

4.3.3  SOFTPRO.  SOFTPRO  has  the  following  error  conditions: 

a.  Message:  "STANDARD  REFERENCE  IN  STANDARD  LINE  _ "  IS  NOT  FOUND 

This  means  that  a  standard  reference  In  the  calculation  field  of  the 
Indicated  line  of  the  standards  file  cannot  be  found. 

b.  Message:  "IN  STANDARDS  FILE,  ERROR  IN  SPECIFYING  CALCULATION  FOR 

STANDARD  LINE 


This  means  that  the  calculation  field  of  the  indicated  line  of  the 
standards  file  is  in  error. 


SPECIFIES  A  CALCULATION 


c.  Message:  "IN  THE  STANDARD  FILE,  LINE 

FOR  A  BASIC  STANDARD" 

This  means  that  for  the  indicated  line  in  the  standards  file,  the 
standard  number  is  between  1  and  14,  indicating  that  it  is  a  basic 
standard,  but  the  calculation  field  contradicts  that  by  providing  a 
calculation. 

d.  Message:  "IN  THE  STANDARDS  FILE,  LINE _  SPECIFIES  A  STANDARD  WHICH 

IS  NOT  BASIC  BUT  IT  HAS  NO  tfOCLATION" 

This  means  that  for  the  indicated  line  in  the  standards  file  the 
standard  number  is  not  between  1  and  14,  indicating  that  it  is  not  a 
basic  standard,  but  there  was  no  calculation  using  basic  standards 
included  in  the  calculation  field. 


4.4  Special  Maintenance  Procedures.  The  normal  procedure  for  executing  a 
“RACftO 5P I T BO L  program  is  to  invoke  the  MACROSPITBOL  interpreter  with  the  com¬ 
mand  line:  $  SPITBOL  <filename>.SPT.  To  save  execution  time  PFA  uses  the 
MACROSPITBOL  feature  of  having  the  source  code  preinterpreted  into  a  SN080L 
executable  file  which  can  then  be  loaded  and  run.  (See  EXIT ( -1 )  in 
MACROSPITBOL  Manual.)  To  facilitate  the  use  of  PFA,  two  command  procedures 
are  required  in  the  user's  LOGIN.COM  file.  The  first  one  is  a  command  to  com¬ 
pile  PFA  programs:  S  C*0MP  :==  $SYS$SYSTEM:SPITBOL/LOAD=PFAEDT  NL : .  This 
command  (compile)  can  then  be  invoked  by  typing  "C"  or  "COMP"  by  the  user  from 
command  level.  The  command  will  then  load  and  run  a  special  PFA  preprocessor 
called  PFAEDT  which  processes  (creates  a  MACROSPITBOL  program)  PFA  source  code 
and  expands  the  "Included"  files.  PFAEDT  then  calls  on  the  MACROSPITBOL 
Interperter  with  the  processed  file,  which  then  creates  the  saveable 
<filename>.SEX  image  file.  The  second  command  entry  is  $  PFA  :==  $SYS$SYSTEM: 
SPIT60L/L0AD=PFAINI  NL:.  This  command,  once  in  the  LOGIN.COM  file,  is  invoked 
by  typing  "PFA"  at  the  command  level.  The  command  will  then  load  and  run  a 
program  called  PFAINI,  which  presents  a  menu  and  asks  for  the  PFA  report 
program  the  user  would  like  to  run.  PFAINI  will  then  load  and  run  the  re¬ 
quested  program  which  had  been  created  by  the  compile  command. 

The  programs  PFAEDT. SPT  and  PFAINI. SPT  used  in  the  command  procedures  (C 
and  PFA)  must  be  compiled  into  loadable  modules  by  the  normal  procedure  out¬ 
lined  above.  The  rest  of  PFA  can  be  compiled  and  run  using  only  the  C  and  PFA 
commands  once  they  have  been  installed. 

4.5  Special  Maintenance  Programs.  None  required. 

4.6  Listings.  Volume  II,  Appendix  E,  contains  all  program  listings. 

4.7  Software  Failure  Report  Summary.  The  following  is  a  summary  of  the  ex¬ 
isting  known  software  failures  and  deficiencies: 


4.7.1  Overall  PFA.  In  list  processing  most  lists  use  commas  as  item  de- 

1 imiters.  HoWever,  lists  of  variables  may  include  multi-subscripted  array 
names  which  contain  commas.  It  is  suggested  that  percent  signs  be  used  in 
place  of  commas  as  primary  list  delimiters  and  that  all  subroutines  used  in 
list  processing  get  as  input  the  delimiter  to  be  searched  for. 

4.7.2  STAMP. 


a.  READPATH  uses  start  nodes  to  determine  which  subroutines  are  called  by 
a  task  and  its  entry  points,  respectively.  However,  it  assumes  that  a  task's 
starting  point  will  always  be  the  first  entry  in  the  path  table.  This  is  not 
always  the  case:  i.e.,  OUTOUT .  It  is  suggested  that  the  entry  points  in  the 
structure  have  the  same  name  as  in  the  routine. 

b.  When  outputting  comments  to  HIPO  charts,  if  the  comment  must  be 
truncated,  STROUT  either  truncates  after  the  last  comma  or  returns  a  null  if 
there  are  no  commas.  Associated  logic  in  OUTPATH  may  cause  the  assocated  line 
of  input  variables  to  be  lost.  It  is  suggested  that  a  separate  routine  be 
written  to  handle  text. 

4.7.3  PATCHANA. 

a.  If  a  module  structure  change  is  found,  it  is  likely  that  everything 
after  the  structure  change  will  be  flagged  because  the  structures  of  the  two 
versions  of  the  module  will  be  out  of  synchronization.  It  is  suggested  that 
the  PATCHANA  program  be  changed  to  apply  pattern  matching  to  the  structural 
patterns  between  parts  of  the  two  versions  of  the  module  being  analyzed  to  de¬ 
termine  the  exact  extent  of  the  change  in  structure  and  to  restore  synchron¬ 
ization  between  the  two  versions  so  that  additional  structural  changes  can  be 
identified.  A  percentage  should  also  be  calculated  to  indicate  the  amount  or 
scope  of  the  change. 

b.  PATCHANA  does  not  recognize  multiple  entry  points.  This  feature  must 
be  added. 

4.8  Future  Program  Improvements.  The  following  program  improvenents  have 
been  suggested  but  are  not  currently  implemented. 

4.8.1  Master  File.  In  general,  changes  in  the  format  of  the  master  file  will 
affect  all  PFA  programs  and  encoders. 

a.  A  new  record  type  "0"  should  be  defined  for  definition  of  global  data, 
similar  to  labeled  and  blank  commons  in  FORTRAN.  This  would  provide  better 
data  tracking  between  modules. 

b.  Establish  variable  use  codes  for  the  variable  records  (type  7  records) 
as  follows: 

"D"  -  defined  in  an  unexecutable  statement 
"M[C]"  -  modified,  may  be  conditional 
"R[C]“  -  referenced,  may  be  conditional 


"T[C]M  -  tested,  may  be  conditional 

M[L]“  -  loop  control,  suffix  to  above 

"CU]“  -  undefined  prior  to  use,  suffix  for  above 

c.  A  new  record  type  "A"  is  needed  to  encode  the  algorithm  used  on  the 
path  segment  in  such  a  way  as  to  allow  theorem  provers  to  be  used  where  pos¬ 
sible. 

4.8.2  STAMP. 

a.  Names  of  modules  of  “blank  common"  and  "labeled  common"  should  be 
included  in  the  module  list  and  processed  as  modules. 


TYPE  OF  MODULE 

NAMING  CONVENTION 

TASK/SUBROUTINE  CODE 

Blank  common 

/*/  or  /  / 

D 

Named  common 

/name/ 

D 

Executable  routine 

name 

S,  T,  E 

Commons  may  or  may  not  be  listed  in  the  structure  chart  but  will  be  listed 
In  HIPO  charts. 

_ _  b.  Version  Information  should  be  deleted  from  the  module  list  and  be  re- 

4  •  placed  with  counts  of  subroutines  calling  each  routine  at  each  level  of  the 
subroutine  hierarchy. 
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APPENDIX  A 

TERMS  AND  ABBREVIATIONS 


TERMS  AND  ABBREVIATIONS 


COMPRO 

Comment  Processor. 

DEC 

Digital  Equipment  Corporation. 

DECUS 

DEC  User  Society. 

Encoder 

A  program  which  reads  the  source  code  for  the  system 
being  analyzed  and  creates  a  master  file  for  use  by 
other  PFA  programs. 

External  procedures 

Procedures  which  exist  outside  of  the  software  being 
analyzed,  e.g.,  operating  system  utilities. 

HIPO 

Hierarchy  plus  Inputs,  Processing,  and  Outputs. 

HIPO  chart 

A  chart  relating  inputs  and  outputs  to  the  processing 
algorithm  which  uses  or  creates  them. 

MACRO SP IT BOL 

A  SN0B0L4  compatible  interpreter  for  the  VAX. 

Master  file 

The  file  which  contains  a  representation  of  the 
attributes  of  the  software  being  analyzed. 

Module 

A  separately  compilable  procedure  or  subroutine. 

Node 

A  point  of  decision  In  execution  path  selection. 

PATCH ANA 

Patch  Analysis  Program. 

Path 

A  segment  of  instructions  which  does  not  contain  any 
branches. 

PFA 

Program  Flow  Analyzer. 

PFALIB 

PFA  Library. 

Program  structure 

Graph  of  the  sequence  of  all  possible  paths  which  may  be 
executed  within  a  program. 

Quantifiers 

A  value  which  quantifies  or  totals  some  attribute  on  a 
path. 

RATFIV 

A  structured  FORTRAN  translator. 
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TERMS  AND  ABBREBI AT  IONS  (Cont'd.) 


SOFT PRO 

Software  Profile  Program. 

Software  patch 

A  change  in  source  code. 

Software  system 

Consists  of  one  or  more  computer  programs  which  perform 
one  or  more  related  functions. 

STAMP 

Structure,  Timing,  Analysis,  Modeling  Program. 

Standards  file 

File  which  contains  user-entered  standards  in  a 
prescribed  format. 

Structure  chart 

Shows  a  subroutine  call  hierarchy  in  the  form  of  a  tree 
graph. 

SYSTRUCT 

System  Structure  Comparison  Program. 

TECOM 

Test  and  Evaluation  Command. 

USAEP6 

U.S.  Army  Electronic  Proving  Ground. 

A-3 


